MCP MS SQL Server

mcp-mssql-server

Um servidor Model Context Protocol (MCP) que fornece uma interface padronizada para modelos de IA interagirem com bancos de dados MS SQL Server. Este servidor implementa a especificação MCP para permitir operações de banco de dados sem interrupções através de uma API consistente.

Recursos

• Executar consultas SQL com suporte a parâmetros
• Listar todas as tabelas no banco de dados
• Descrever esquemas de tabelas
• Suporte para modos de transporte stdio e HTTP
• Sistema de registro abrangente
• Configuração baseada em ambiente
• Tratamento de erros e desligamento gracioso

Pré-requisitos

• Node.js (versão que suporta módulos ES)
• Instância do MS SQL Server
• Credenciais de acesso para o banco de dados

Instalação

1. Clone o repositório
2. Instale as dependências:

npm install

Você também pode instalar o pacote globalmente:

npm install -g mcp-mssql-server

3. Crie um arquivo .env na raiz do projeto com as seguintes variáveis obrigatórias:

DB_SERVER=your_server_address
DB_USER=your_username
DB_PASSWORD=your_password
DB_DATABASE_NAME=your_database_name

Uso

O servidor pode ser iniciado em dois modos de transporte diferentes:

Modo stdio (Padrão)

npm start
# or
npm run start:stdio

Modo HTTP

npm run start:http

Modo de Desenvolvimento

npm run dev

Protocolo JSON-RPC

O servidor implementa o protocolo JSON-RPC 2.0 com os seguintes métodos principais:

1. initialize - Inicializar a conexão do servidor:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {}
    },
    "clientInfo": {
      "name": "your-client",
      "version": "1.0.0"
    }
  }
}

2. tools/list - Listar ferramentas disponíveis
3. tools/call - Chamar uma ferramenta específica

Testes

O pacote inclui um cliente de teste (test.package.js) que demonstra como interagir com o servidor MCP:

node test.package.js

O cliente de teste implementa uma classe MCPTestClient que:

• Inicia um processo do servidor usando npx mcp-mssql-server
• Inicializa a conexão com a versão do protocolo '2024-11-05'
• Lista as ferramentas disponíveis
• Executa consultas de exemplo incluindo:
  • Listar todas as tabelas
  • Executar uma consulta SQL específica para contar documentos
• Trata respostas e erros do servidor através de fluxos stdio
• Inclui tratamento adequado de erros e limpeza de processos

Exemplo de consulta de teste do cliente:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "execute_sql_query",
    "arguments": {
      "query": "SELECT COUNT(*) as document_count FROM document_new"
    }
  }
}

O cliente de teste fornece uma maneira simples de verificar a funcionalidade do servidor e pode servir como referência para implementar seu próprio cliente.

Ferramentas Disponíveis

O servidor fornece as seguintes ferramentas MCP:

1. execute_sql_query

Executar consultas SQL contra o banco de dados com parametrização opcional.

{
  "query": "SELECT * FROM Users WHERE id = @userId",
  "parameters": [
    {
      "name": "userId",
      "type": "int",
      "value": 1
    }
  ]
}

2. list_tables

Listar todas as tabelas disponíveis no banco de dados conectado.

3. describe_table

Obter informações detalhadas do esquema para uma tabela específica.

{
  "table_name": "Users"
}

Registro

Os registros são armazenados no diretório logs:

• error.log: Registros de nível de erro
• combined.log: Todos os registros

No modo HTTP, os registros também são enviados para o console.

Dependências

Dependências principais:

• @modelcontextprotocol/sdk: ^1.13.0
• dotenv: ^16.4.5
• express: ^5.1.0
• mssql: ^11.0.1
• winston: ^3.11.0

Dependências de desenvolvimento:

• axios: ^1.10.0

Licença

MIT

Contribuindo

1. Faça um fork do repositório
2. Crie sua branch de recurso
3. Faça commit das suas alterações
4. Envie para a branch
5. Crie uma nova Solicitação de Pull