MCP-Haskell

Uma implementação completa do Model Context Protocol (MCP) para Haskell, com suporte tanto para transporte StdIO quanto HTTP.

GitHub

Experimente este MCPPatrocinado

Documentação

MCP — Model Context Protocol para Haskell

Uma implementação completa do Model Context Protocol (MCP) para Haskell, dividida em dois pacotes:

mcp-types — Tipos de protocolo puros com dependências mínimas (aeson, base, containers, text)
mcp — Servidor HTTP baseado em Servant com autenticação JWT

Visão Geral

Este repositório fornece uma implementação type-safe do Model Context Protocol em Haskell. MCP é um protocolo aberto que padroniza como aplicações fornecem contexto a Grandes Modelos de Linguagem (LLMs), permitindo que modelos de IA se conectem com segurança a fontes de dados e ferramentas.

Recursos

Suporte ao Protocolo Mais Recente: Implementa a versão 2025-06-18 do protocolo MCP
Implementação Completa do Protocolo MCP: Todos os tipos de mensagem MCP, requisições, respostas e notificações
Design Type-Safe: Integração completa com o sistema de tipos de Haskell com serialização JSON automática via Aeson
Transporte HTTP: Servidor HTTP baseado em Servant com respostas SSE em streaming
Autenticação JWT: Autenticação segura via servant-auth-server
Interface de Servidor Extensível: Framework de handlers configurável para implementar servidores MCP personalizados
Framework de Ferramentas: Funções auxiliares para definir ferramentas com validação de entrada e resultados estruturados

Arquitetura

A implementação está organizada em dois pacotes:

`mcp-types`

Tipos de protocolo centrais com dependências mínimas — adequados para construir clientes ou implementações alternativas de servidor.

MCP.Types: Tipos de dados MCP centrais (Content, Resource, Tool, Prompt, Capability, etc.)
MCP.Protocol: Wrappers de mensagens JSON-RPC 2.0, todos os tipos de requisição/resposta cliente/servidor, tipos de notificação
MCP.Aeson: Opções personalizadas de parsing Aeson

`mcp`

Implementação de servidor baseada em Servant. Reexporta MCP.Protocol e MCP.Types por conveniência.

MCP.Server: Infraestrutura central do servidor com transformador de mônada MCPServerT, registro ProcessHandlers, framework ToolHandler, API Servant autenticada por JWT, gerenciamento de estado do servidor e roteamento de requisições

Para autorização OAuth 2.0 em clientes MCP, consulte oauth2-server.

Suporte ao Protocolo MCP

Operação	Descrição	Status
`initialize`	Iniciar sessão e negociar capacidades	Suportado
`ping`	Verificação de saúde	Suportado
`resources/list`	Listar recursos disponíveis	Suportado
`resources/templates/list`	Listar modelos de recursos disponíveis	Suportado
`resources/read`	Ler conteúdos de recursos	Suportado
`resources/subscribe`	Assinar atualizações de recursos	Suportado
`resources/unsubscribe`	Cancelar assinatura de atualizações de recursos	Suportado
`prompts/list`	Listar prompts disponíveis	Suportado
`prompts/get`	Obter prompt com argumentos	Suportado
`tools/list`	Listar ferramentas disponíveis	Suportado
`tools/call`	Executar uma ferramenta	Suportado
`completion/complete`	Autocompletar com contexto	Suportado
`logging/setLevel`	Definir nível de registro	Suportado
`sampling/createMessage`	Solicitar amostragem de LLM	Suportado
`roots/list`	Listar diretórios raiz do cliente	Suportado
`elicitation/create`	Solicitar entrada do usuário via formulários	Suportado

Instalação

Para uma implementação de servidor, adicione mcp ao seu build-depends:

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

Se você precisar apenas dos tipos de protocolo (por exemplo, para um cliente), dependa de mcp-types em vez disso:

build-depends:
    base
  , aeson
  , mcp-types

Este projeto tem como alvo GHC 9.12 (veja cabal.project).

Início 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 Exemplo

Um servidor de exemplo totalmente documentado está em mcp-server/example/. Ele demonstra todos os principais recursos: ferramentas, recursos, modelos de recursos, prompts, completions, registro, hooks de ciclo de vida e autenticação JWT.

Executar o exemplo

cabal run mcp-example

O servidor inicia em http://localhost:8080/mcp e imprime um token bearer JWT na saída padrão. Use-o no cabeçalho Authorization para todas as requisições:

# 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 exemplos de curl cobrindo todos os 15 endpoints.

Estrutura do Projeto

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

Desenvolvimento

cabal build all
cabal test all

Licença

MPL-2.0 — veja LICENSE neste repositório.