mcp-server-toolkit

---

Por qué existe esto

Cuando le pides a Claude Code "where do we handle Stripe webhooks?" tiene dos malas opciones:

• Opción A — Leer cada archivo del repositorio. Lento, costoso, y revienta la ventana de contexto en cualquier base de código real.
• Opción B — Adivinar basándose en los primeros archivos que ve. Se equivoca la mitad de las veces.

MCP Server Toolkit les da a los agentes una tercera opción: preguntar directamente a la herramienta correcta. Búsqueda semántica de código, consultas en vivo a bases de datos, búsquedas en documentación, introspección de APIs — todo a través del estándar Model Context Protocol, para que cualquier cliente compatible con MCP pueda usarlos sin cambios en tu código existente.

---

✨ Características

• 🔍 Búsqueda semántica de código — Encuentra la función, archivo o patrón correcto en todo tu repositorio en milisegundos. Impulsada por embeddings vectoriales, sin necesidad de Elasticsearch.
• 📚 Servidor de documentación — Dale a tu agente acceso instantáneo a cualquier sitio de documentación, archivos Markdown locales o espacio de Notion.
• 🗄️ Servidor de base de datos — Lenguaje natural → SQL para PostgreSQL, MySQL y SQLite. Solo lectura por defecto, escritura con una bandera explícita.
• 🌐 Servidor de introspección de APIs — Carga cualquier especificación OpenAPI/Swagger y deja que tu agente navegue y llame endpoints con seguridad de tipos.
• ⚡ Configuración con un comando — Cada servidor se distribuye como CLI independiente. npx y rutas de instalación pip incluidas.
• 🔒 Secretos sin configuración — Lee de tu archivo .env existente o de variables de entorno. Nada nuevo que aprender.
• 🧩 Funciona en todas partes — Claude Code, Cursor, Windsurf, Cline, VS Code Copilot, Codex CLI, Gemini CLI y cualquier otro cliente compatible con MCP.
• 🛠️ Extensible — El helper createServer() reduce una nueva herramienta a ~15 líneas de TypeScript. Crea un servidor personalizado en 30 segundos.

---

🚀 Inicio rápido

Requisitos: Node.js 18+ o Python 3.10+

Opción A — npx (sin instalación)

npx mcp-server-toolkit@latest init

Esto ejecuta el asistente de configuración interactivo. Elige tus servidores, pega tus credenciales y obtén un bloque de configuración listo para pegar en Claude Code / Cursor.

---

Opción B — instalación global con npm

npm install -g mcp-server-toolkit
mcp init

---

Opción C — pip (entornos Python)

pip install mcp-server-toolkit
mcp init

---

Añadir a Claude Code

Después de mcp init, copia el bloque generado en tu .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"]
    }
  }
}

Eso es todo. Reinicia Claude Code y tu agente ahora tiene acceso completo a los tres.

---

📦 Servidores incluidos

Servidor	Instalación	Qué hace
mcp-code-search	npx mcp-code-search	Búsqueda semántica + por palabras clave en tu base de código
mcp-database	npx mcp-database	Consultas en lenguaje natural para Postgres, MySQL, SQLite
mcp-docs	npx mcp-docs	Indexa y consulta Markdown local, Notion o cualquier URL
mcp-openapi	npx mcp-openapi	Navega y llama endpoints desde cualquier especificación OpenAPI
mcp-git	npx mcp-git	Consulta commits, diffs, blame y ramas
mcp-shell	npx mcp-shell	Ejecución de shell en sandbox con controles de lista blanca

Todos los servidores son instalables de forma independiente — usa uno o todos.

---

🛠️ Ejemplo de uso

Una vez instalado, tu agente de IA puede usar lenguaje natural para interactuar con todo tu entorno de desarrollo:

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..."

Sin copiar y pegar. Sin cambiar de contexto. El agente simplemente lo sabe.

---

🔧 Construye tu propio servidor

Crea un nuevo servidor en 30 segundos:

mcp new my-server --template typescript

Esto genera:

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

Una herramienta mínima se ve así:

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();

Eso es todo. Envíalo.

---

📁 Estructura del proyecto

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

---

🗺️ Hoja de ruta

• Búsqueda de código (semántica + por palabras clave)
• Servidor PostgreSQL / MySQL / SQLite
• Servidor de documentación (Markdown + rastreo de URLs)
• Servidor de introspección OpenAPI
• Servidor Notion
• Servidor Linear / Jira
• Soporte para bases de datos gestionadas Supabase + PlanetScale
• Interfaz web para navegar por las herramientas registradas
• Descripciones de herramientas generadas automáticamente desde el esquema

¿Quieres que algo de esta lista tenga prioridad? Abre un issue y añade un 👍.

---

🤝 Contribuciones

Las contribuciones son lo que hace que este proyecto merezca una estrella. Así es como puedes participar:

¿Primera vez?

1. Busca issues etiquetados como good first issue — están acotados a propósito para ser pequeños.
2. Comenta en el issue para reclamarlo antes de empezar.
3. Haz un fork del repositorio, haz tus cambios y abre un PR.

Añadir un nuevo servidor

El camino más rápido hacia un PR fusionado:

# 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 nuevo servidor necesita:

• Un README.md que explique qué hace y el comando de instalación de una línea
• Al menos una prueba en __tests__/
• Un bloque de configuración de ejemplo para Claude Code / Cursor

Directrices

• Mantén cada herramienta enfocada en hacer una cosa bien — resiste la tentación de ampliar el alcance.
• Nunca almacenes credenciales en el código — siempre lee de variables de entorno.
• Añade tu servidor a la tabla del README principal y a la lista packages/.

Código de conducta

Sé excelente con los demás. Consulta CODE_OF_CONDUCT.md.

---

🔐 Seguridad

• Todos los servidores son de solo lectura por defecto. El acceso de escritura requiere una bandera --writable explícita.
• Las credenciales se leen solo de variables de entorno — nunca se escriben en el código ni se registran.
• El servidor de shell usa una lista blanca (mcp-shell.config.json) — sin ejecución arbitraria de comandos.
• ¿Encontraste una vulnerabilidad? Envía un correo a security@naveenayalla1-CS50.dev en lugar de abrir un issue público.

---

📄 Licencia

MIT © 2026 naveenayalla1-CS50

Eres libre de usar esto en proyectos personales, productos comerciales y cualquier cosa intermedia. Se agradece la atribución, pero no es obligatoria.

---

Uso del servidor MCP

Este repositorio contiene un kit de herramientas de servidores MCP en TypeScript/Node.js.

Instalación

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 del servidor MCP

Este repositorio contiene un kit de herramientas de servidores MCP en TypeScript/Node.js.

### Instalación

```bash
npm install
npm run build