mcp-server-toolkit

---

Por que isso existe

Quando você pergunta ao Claude Code "where do we handle Stripe webhooks?", ele tem duas opções ruins:

• Opção A — Ler todos os arquivos do repositório. Lento, caro, estoura a janela de contexto em qualquer base de código real.
• Opção B — Adivinhar com base nos primeiros arquivos que vê. Errado metade das vezes.

O MCP Server Toolkit dá aos agentes uma terceira opção: perguntar diretamente à ferramenta certa. Busca semântica de código, consultas ao vivo em banco de dados, consultas a documentação, introspecção de API — tudo disponibilizado através do padrão Model Context Protocol, para que qualquer cliente compatível com MCP possa usá-los sem alterações no seu código existente.

---

✨ Recursos

• 🔍 Busca semântica de código — Encontre a função, arquivo ou padrão certo em todo o seu repositório em milissegundos. Alimentado por embeddings vetoriais, sem necessidade de Elasticsearch.
• 📚 Servidor de documentação — Dê ao seu agente acesso instantâneo a qualquer site de documentação, arquivos Markdown locais ou workspace do Notion.
• 🗄️ Servidor de banco de dados — Linguagem natural → SQL para PostgreSQL, MySQL e SQLite. Somente leitura por padrão, gravável com uma flag explícita.
• 🌐 Servidor de introspecção de API — Carregue qualquer especificação OpenAPI/Swagger e deixe seu agente navegar e chamar endpoints com segurança de tipos.
• ⚡ Configuração em um comando — Cada servidor é distribuído como um CLI independente. npx e caminhos de instalação pip incluídos.
• 🔒 Segredos sem configuração — Lê do seu arquivo .env existente ou de variáveis de ambiente. Nada novo para aprender.
• 🧩 Funciona em qualquer lugar — Claude Code, Cursor, Windsurf, Cline, VS Code Copilot, Codex CLI, Gemini CLI e qualquer outro cliente compatível com MCP.
• 🛠️ Extensível — O helper createServer() reduz uma nova ferramenta a ~15 linhas de TypeScript. Crie um servidor personalizado em 30 segundos.

---

🚀 Início Rápido

Requisitos: Node.js 18+ ou Python 3.10+

Opção A — npx (sem instalação)

npx mcp-server-toolkit@latest init

Isso executa o assistente de configuração interativo. Escolha seus servidores, cole suas credenciais e obtenha um bloco de configuração pronto para colar no Claude Code / Cursor.

---

Opção B — instalação global via npm

npm install -g mcp-server-toolkit
mcp init

---

Opção C — pip (ambientes Python)

pip install mcp-server-toolkit
mcp init

---

Adicionar ao Claude Code

Após mcp init, copie o bloco gerado para o seu .claude/mcp.json:

{
  "servers": {
    "code-search": {
      "command": "mcp-code-search",
      "args": ["--root", "."],
      "env": { "OPENAI_API_KEY": "${OPENAI_API_KEY}" }
    },
    "database": {
      "command": "mcp-database",
      "args": ["--read-only"],
      "env": { "DATABASE_URL": "${DATABASE_URL}" }
    },
    "docs": {
      "command": "mcp-docs",
      "args": ["--source", "./docs"]
    }
  }
}

Pronto. Reinicie o Claude Code e seu agente agora tem acesso total a todos os três.

---

📦 Servidores Incluídos

Servidor	Instalação	O que faz
mcp-code-search	npx mcp-code-search	Busca semântica + por palavras-chave na sua base de código
mcp-database	npx mcp-database	Consultas em linguagem natural para Postgres, MySQL, SQLite
mcp-docs	npx mcp-docs	Indexa e consulta Markdown local, Notion ou qualquer URL
mcp-openapi	npx mcp-openapi	Navega e chama endpoints de qualquer especificação OpenAPI
mcp-git	npx mcp-git	Consulta commits, diffs, blame e branches
mcp-shell	npx mcp-shell	Execução de shell em sandbox com controles de allowlist

Todos os servidores são instaláveis de forma independente — use um ou todos.

---

🛠️ Exemplo de Uso

Depois de instalado, seu agente de IA pode usar linguagem natural para interagir com todo o seu ambiente de desenvolvimento:

You:  "Find all places where we validate user input before inserting into the DB"

Agent uses mcp-code-search →
  Found 7 matches in: auth/validators.ts, api/users.ts, api/orders.ts...

You:  "How many users signed up in the last 7 days?"

Agent uses mcp-database →
  SELECT count(*) FROM users WHERE created_at > now() - interval '7 days';
  → 1,432 new users

You:  "What does our docs say about rate limiting?"

Agent uses mcp-docs →
  Found in docs/api/rate-limits.md: "All endpoints are limited to 100 req/min per API key..."

Sem copiar e colar. Sem troca de contexto. O agente simplesmente sabe.

---

🔧 Construa Seu Próprio Servidor

Crie um novo servidor em 30 segundos:

mcp new my-server --template typescript

Isso gera:

my-server/
├── src/
│   ├── index.ts        # Entry point — register your tools here
│   └── tools/
│       └── example.ts  # Your first tool
├── package.json
└── README.md

Uma ferramenta mínima se parece com isto:

import { createServer, tool, z } from 'mcp-server-toolkit';

const server = createServer({ name: 'my-server', version: '1.0.0' });

server.addTool(
  tool({
    name: 'get_weather',
    description: 'Get current weather for a city',
    input: z.object({ city: z.string() }),
    run: async ({ city }) => {
      const data = await fetchWeather(city);
      return { content: `${city}: ${data.temp}°C, ${data.condition}` };
    },
  })
);

server.start();

É só isso. Pode publicar.

---

📁 Estrutura do Projeto

mcp-server-toolkit/
├── packages/
│   ├── core/           # createServer(), tool(), z helpers
│   ├── code-search/    # Semantic codebase search server
│   ├── database/       # Natural language DB query server
│   ├── docs/           # Documentation indexing server
│   ├── openapi/        # OpenAPI spec introspection server
│   ├── git/            # Git history and diff server
│   └── shell/          # Sandboxed shell server
├── examples/
│   ├── claude-code/    # Drop-in config for Claude Code
│   ├── cursor/         # Drop-in config for Cursor
│   └── custom-server/  # Starter template for custom tools
├── docs/               # Full documentation
└── CONTRIBUTING.md

---

🗺️ Roadmap

• Busca de código (semântica + palavras-chave)
• Servidor PostgreSQL / MySQL / SQLite
• Servidor de documentação (Markdown + rastreamento de URL)
• Servidor de introspecção OpenAPI
• Servidor Notion
• Servidor Linear / Jira
• Suporte a bancos de dados gerenciados Supabase + PlanetScale
• Interface web para navegar pelas ferramentas registradas
• Descrições de ferramentas geradas automaticamente a partir do schema

Quer que algo desta lista seja priorizado? Abra uma issue e adicione um 👍.

---

🤝 Contribuindo

Contribuições são o que fazem este projeto merecer estrelas. Veja como participar:

Primeira vez?

1. Procure issues rotuladas como good first issue — elas são propositalmente pequenas em escopo.
2. Comente na issue para reivindicá-la antes de começar.
3. Faça um fork do repositório, faça suas alterações e abra um PR.

Adicionando um novo servidor

O caminho mais rápido para um PR mesclado:

# Clone and install deps
git clone https://github.com/naveenayalla1-CS50/mcp-server-toolkit
cd mcp-server-toolkit
npm install

# Scaffold your server
npm run new-server -- --name my-awesome-server

# Run tests
npm test

# Submit your PR

Cada novo servidor precisa de:

• Um README.md explicando o que ele faz e o comando de instalação em uma linha
• Pelo menos um teste em __tests__/
• Um bloco de configuração de exemplo para Claude Code / Cursor

Diretrizes

• Mantenha cada ferramenta focada em fazer uma coisa bem feita — evite expansão de escopo.
• Nunca armazene credenciais no código — sempre leia de variáveis de ambiente.
• Adicione seu servidor à tabela no README principal e à lista packages/.

Código de Conduta

Seja excelente uns com os outros. Veja CODE_OF_CONDUCT.md.

---

🔐 Segurança

• Todos os servidores são somente leitura por padrão. Acesso de escrita requer uma flag --writable explícita.
• Credenciais são lidas apenas de variáveis de ambiente — nunca codificadas ou registradas em logs.
• O servidor de shell usa uma allowlist (mcp-shell.config.json) — sem execução arbitrária de comandos.
• Encontrou uma vulnerabilidade? Envie um e-mail para security@naveenayalla1-CS50.dev em vez de abrir uma issue pública.

---

📄 Licença

MIT © 2026 naveenayalla1-CS50

Você é livre para usar isto em projetos pessoais, produtos comerciais e qualquer coisa entre os dois. Atribuição é apreciada, mas não obrigatória.

---

Uso do servidor MCP

Este repositório contém um toolkit TypeScript/Node.js de servidores MCP.

Instalação

npm install
npm run build
npm run build --workspace=@mcp-toolkit/core
npm run build --workspace=@mcp-toolkit/code-search
node packages/code-search/dist/index.js



## Uso do servidor MCP

Este repositório contém um toolkit TypeScript/Node.js de servidores MCP.

### Instalação

```bash
npm install
npm run build