MCP-Haskell

Una implementación completa del Model Context Protocol (MCP) para Haskell, compatible con transporte StdIO y HTTP.

Documentación

MCP — Protocolo de Contexto de Modelo para Haskell

Una implementación completa del Protocolo de Contexto de Modelo (MCP) para Haskell, dividida en dos paquetes:

mcp-types — Tipos de protocolo puros con dependencias mínimas (aeson, base, containers, text)
mcp — Servidor HTTP basado en Servant con autenticación JWT

Resumen

Este repositorio proporciona una implementación type-safe del Protocolo de Contexto de Modelo en Haskell. MCP es un protocolo abierto que estandariza cómo las aplicaciones proporcionan contexto a los Modelos de Lenguaje de Gran Escala (LLMs), permitiendo que los modelos de IA se conecten de forma segura a fuentes de datos y herramientas.

Características

Soporte del Protocolo más Reciente: Implementa la versión 2025-06-18 del protocolo MCP
Implementación Completa del Protocolo MCP: Todos los tipos de mensajes MCP, solicitudes, respuestas y notificaciones
Diseño Type-Safe: Integración completa con el sistema de tipos de Haskell con serialización JSON automática mediante Aeson
Transporte HTTP: Servidor HTTP basado en Servant con respuestas SSE en streaming
Autenticación JWT: Autenticación segura mediante servant-auth-server
Interfaz de Servidor Extensible: Marco de trabajo de manejadores configurable para implementar servidores MCP personalizados
Marco de Herramientas: Funciones auxiliares para definir herramientas con validación de entrada y resultados estructurados

Arquitectura

La implementación está organizada en dos paquetes:

`mcp-types`

Tipos de protocolo centrales con dependencias mínimas — adecuado para construir clientes o implementaciones alternativas de servidores.

MCP.Types: Tipos de datos MCP centrales (Content, Resource, Tool, Prompt, Capability, etc.)
MCP.Protocol: Envoltorios de mensajes JSON-RPC 2.0, todos los tipos de solicitud/respuesta de cliente/servidor, tipos de notificación
MCP.Aeson: Opciones personalizadas de análisis Aeson

`mcp`

Implementación de servidor basada en Servant. Re-exporta MCP.Protocol y MCP.Types por conveniencia.

MCP.Server: Infraestructura central del servidor con transformador de mónada MCPServerT, registro ProcessHandlers, marco de trabajo ToolHandler, API Servant autenticada con JWT, gestión de estado del servidor y enrutamiento de solicitudes

Para autorización OAuth 2.0 en clientes MCP, consulte oauth2-server.

Soporte del Protocolo MCP

Operación	Descripción	Estado
`initialize`	Iniciar sesión y negociar capacidades	Soportado
`ping`	Verificación de salud	Soportado
`resources/list`	Listar recursos disponibles	Soportado
`resources/templates/list`	Listar plantillas de recursos disponibles	Soportado
`resources/read`	Leer contenidos de recursos	Soportado
`resources/subscribe`	Suscribirse a actualizaciones de recursos	Soportado
`resources/unsubscribe`	Cancelar suscripción a actualizaciones de recursos	Soportado
`prompts/list`	Listar prompts disponibles	Soportado
`prompts/get`	Obtener prompt con argumentos	Soportado
`tools/list`	Listar herramientas disponibles	Soportado
`tools/call`	Ejecutar una herramienta	Soportado
`completion/complete`	Autocompletado con contexto	Soportado
`logging/setLevel`	Establecer nivel de registro	Soportado
`sampling/createMessage`	Solicitar muestreo LLM	Soportado
`roots/list`	Listar directorios raíz del cliente	Soportado
`elicitation/create`	Solicitar entrada del usuario mediante formularios	Soportado

Instalación

Para una implementación de servidor, agregue mcp a su build-depends:

build-depends:
    base
  , servant
  , servant-server
  , servant-auth-server
  , aeson
  , mcp

Si solo necesita los tipos de protocolo (por ejemplo, para un cliente), dependa de mcp-types en su lugar:

build-depends:
    base
  , aeson
  , mcp-types

Este proyecto está dirigido a GHC 9.12 (consulte cabal.project).

Inicio Rápido

{-# LANGUAGE DataKinds #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE TypeFamilies #-}

import Control.Concurrent.MVar (newMVar)
import MCP.Server

-- Define your handler state and user types
type instance MCPHandlerState = ()
type instance MCPHandlerUser  = MyUser

-- Create server state with capabilities
mkServerState :: IO (MVar MCPServerState)
mkServerState = do
  let impl = Implementation "my-server" "1.0.0" Nothing
      caps = ServerCapabilities
        { logging      = Nothing
        , prompts      = Nothing
        , resources    = Nothing
        , tools        = Just (ToolsCapability { listChanged = Just True })
        , completions  = Nothing
        , experimental = Nothing
        }
      handlers = withToolHandlers myTools defaultProcessHandlers
  newMVar $ initMCPServerState () Nothing Nothing caps impl Nothing handlers

-- Define tools using the ToolHandler framework
myTools :: [ToolHandler]
myTools =
  [ toolHandler "greet" (Just "Say hello") greetSchema $ \_args ->
      return $ ProcessSuccess $ toolTextResult ["Hello!"]
  ]

Servidor de Ejemplo

Un servidor de ejemplo completamente documentado se encuentra en mcp-server/example/. Demuestra cada característica principal: herramientas, recursos, plantillas de recursos, prompts, completados, registro, enlaces del ciclo de vida y autenticación JWT.

Ejecutar el ejemplo

cabal run mcp-example

El servidor se inicia en http://localhost:8080/mcp e imprime un token portador JWT en stdout. Úselo en el encabezado Authorization para todas las solicitudes:

# Initialize the session (replace $TOKEN with the printed token)
curl -s -X POST http://localhost:8080/mcp \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

# Send initialized notification
curl -s -X POST http://localhost:8080/mcp \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized","params":null}'

# List available tools
curl -s -X POST http://localhost:8080/mcp \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# Call the add tool
curl -s -X POST http://localhost:8080/mcp \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"add","arguments":{"a":17,"b":25}}}'

Consulte mcp-server/example/SKILL.md para ejemplos de curl que cubren los 15 endpoints.

Estructura del Proyecto

mcp-types/               # Core protocol types package
├── src/MCP/
│   ├── Aeson.hs             # Custom Aeson parsing options
│   ├── Protocol.hs          # JSON-RPC protocol messages
│   └── Types.hs             # Core MCP data types
└── mcp-types.cabal

mcp-server/               # Server implementation package
├── src/MCP/
│   ├── Server.hs            # Re-exports Common, HTTP, and Stdio
│   └── Server/
│       ├── Common.hs        # Types, state, request routing, tool helpers
│       ├── HTTP.hs          # Servant-based HTTP transport with JWT auth
│       └── Stdio.hs         # Stdio transport
├── test/
│   ├── Main.hs              # Test entry point
│   └── MCP/
│       ├── Integration.hs       # HTTP integration tests (hspec-wai)
│       ├── StdioIntegration.hs  # Stdio integration tests
│       ├── TestServer.hs        # Test server configuration
│       └── TestUtils.hs         # Test utilities and request builders
├── example/
│   ├── Main.hs              # Example server (tools, resources, prompts, etc.)
│   ├── mcp-example.cabal    # Standalone cabal project
│   ├── mcp-config.json      # Claude Desktop MCP configuration template
│   └── SKILL.md             # Build, run, and test instructions
└── mcp.cabal

Desarrollo

cabal build all
cabal test all

Licencia

MPL-2.0 — consulte LICENSE en este repositorio.