mcp-suite

Un servidor MCP de TypeScript de grado de producción que proporciona a los agentes de IA (Claude Desktop, Cursor, Windsurf, agentes personalizados) acceso estructurado a datos del mundo real en cuatro dominios: mercados financieros, Web3/DeFi, herramientas de desarrollo y atención médica (FHIR).

• Primero la autenticación: validación JWT habilitada por defecto

• Aislamiento de dominios: la falta de claves API deshabilita un dominio, no todo el servidor

• Caché de respuesta (LRU + TTL) y limitación de tasa de token-bucket por dominio

• Esquemas tipados (Zod) en cada entrada y salida de herramienta

• Dos transportes: stdio (local) y HTTP + SSE (remoto/alojado)

Inicio rápido

# Run directly (no global install required)
npx mcp-suite

# Or install globally
npm install -g mcp-suite
mcp-suite

Requisitos: Node.js ≥ 20, npm ≥ 10

Instalación

1. Configurar variables de entorno

Copie .env.example a .env y rellene las claves para los dominios que desea habilitar:

cp .env.example .env

# Authentication (required in production)
MCP_JWT_SECRET=your-secret-here

# Financial Markets (Alpha Vantage + CoinGecko)
ALPHA_VANTAGE_API_KEY=

# Web3 / DeFi (Alchemy + OpenSea + Blur)
ALCHEMY_API_KEY=
OPENSEA_API_KEY=

# Developer Tools (GitHub)
GITHUB_TOKEN=

# Healthcare / FHIR (optional — defaults to public HAPI sandbox)
FHIR_BASE_URL=https://hapi.fhir.org/baseR4

# Server
LOG_LEVEL=info         # debug | info | warn | error
MCP_PORT=3000          # HTTP transport only
AUTH_DISABLED=false    # set true for local dev only

Solo necesita claves para los dominios que utiliza. Los dominios con claves faltantes se deshabilitan silenciosamente al iniciar.

2. Generar un token de desarrollo

npx mcp-suite gen-token
# eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

3. Añadir a Claude Desktop

Añada a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "mcp-suite": {
      "command": "npx",
      "args": ["mcp-suite"],
      "env": {
        "MCP_JWT_SECRET": "your-secret-here",
        "ALPHA_VANTAGE_API_KEY": "...",
        "ALCHEMY_API_KEY": "...",
        "OPENSEA_API_KEY": "...",
        "GITHUB_TOKEN": "..."
      }
    }
  }
}

4. Iniciar como servidor HTTP (despliegues remotos/alojados)

npx mcp-suite --transport http --port 3000

Esto expone GET /health, GET /tools y el endpoint SSE para clientes MCP remotos.

Comandos CLI

Herramientas disponibles

Mercados financieros

Desarrollado por Alpha Vantage y CoinGecko. Requiere: ALPHA_VANTAGE_API_KEY

Ejemplo:

{ "tool": "get_stock_quote", "arguments": { "ticker": "NVDA" } }

Web3 / DeFi

Desarrollado por Alchemy, OpenSea y Blur. Requiere: ALCHEMY_API_KEY, OPENSEA_API_KEY

Ejemplo:

{ "tool": "get_nft_floor", "arguments": { "collection_slug": "boredapeyachtclub" } }

Herramientas de desarrollo

Desarrollado por la API de GitHub. Requiere: GITHUB_TOKEN

Ejemplo:

{ "tool": "get_pipeline_status", "arguments": { "repo": "vercel/next.js", "branch": "canary" } }

Atención médica (FHIR)

Desarrollado por HAPI FHIR R4. Requiere: nada (por defecto a sandbox público) o FHIR_BASE_URL para endpoints personalizados.

Aviso HIPAA: Todas las herramientas de atención médica se conectan a un sandbox público solo con datos sintéticos. No se accede a información de salud del paciente (PHI) real. Para uso en producción, reemplace FHIR_BASE_URL con un endpoint EHR compatible con HIPAA y configure las credenciales SMART on FHIR OAuth 2.0 adecuadas.

Ejemplo:

{ "tool": "lookup_patient", "arguments": { "name": "Smith", "birth_date": "1980-01-15" } }

Autenticación

La autenticación está habilitada por defecto. Cada llamada a una herramienta debe llevar un JWT válido.

Producción

Establezca MCP_JWT_SECRET en un secreto fuerte. El servidor se niega a iniciarse en modo de producción sin él.

Desarrollo

Opción A — deshabilitar la autenticación por completo (solo local):

AUTH_DISABLED=true

Opción B — usar un JWT de desarrollo:

npx mcp-suite gen-token

Pase el token generado en el campo _meta de la solicitud MCP (stdio) o en el encabezado Authorization: Bearer (HTTP).

Estructura JWT

{
  "sub": "your-client-id",
  "scope": "mcp:tools",
  "iat": 1713484800,
  "exp": 1716076800
}

Arquitectura

MCP Clients (Claude Desktop · Cursor · Windsurf · Custom Agents)
        │  MCP Protocol
┌───────▼────────────────────────────────────────┐
│  Transport Layer  (stdio  |  HTTP + SSE)        │
├────────────────────────────────────────────────┤
│  Auth Middleware  (JWT validation / bypass)     │
├────────────────────────────────────────────────┤
│  Tool Registry    (register · list · route)     │
├──────────┬──────────┬──────────┬───────────────┤
│Financial │  Web3    │ DevTools │  Healthcare   │
├──────────┴──────────┴──────────┴───────────────┤
│  Shared: Rate Limiter · Cache · Logger · Errors │
└─────────────────────────────────────────────────┘
         │           │          │          │
   Alpha Vantage  Alchemy   GitHub API  HAPI FHIR
   CoinGecko      OpenSea
                  Blur

• Caché: Caché en proceso LRU + TTL (node-cache). Los TTL son apropiados para el dominio (15s para cripto, 300s para estadísticas de repositorio de GitHub).

• Limitación de tasa: Token-bucket por dominio que protege las cuotas de API de nivel gratuito.

• Tipos de error: AuthError, ValidationError, DomainUnavailableError, UpstreamError, RateLimitError — todos producen respuestas de error MCP estructuradas.

• Registro: JSON estructurado en cada llamada a herramienta: dominio, nombre de herramienta, latencia, acierto de caché, estado.

Añadir un dominio

Cada dominio sigue el mismo patrón. Para añadir un nuevo dominio:

1. Cree src/domains/[name]/ con index.ts, schemas.ts, client.ts y tools/

2. Exporte un objeto Domain:

export const myDomain: Domain = {
  name: 'my-domain',
  isAvailable: () => !!config.MY_API_KEY,
  registerTools: (server) => { /* server.tool(...) calls */ }
}

3. Regístrelo en src/server.ts

4. Documente las herramientas en docs/API.md

Consulte docs/TDD.md §5 y docs/CODING_STANDARDS.md para ver el patrón completo.

Desarrollo

git clone https://github.com/ayenisholah/mcp-suite.git
cd mcp-suite
npm install
cp .env.example .env   # fill in your API keys

npm run build          # compile TypeScript → dist/
npm run dev            # watch mode
npm run typecheck      # type check without emit
npm run lint           # ESLint
npm test               # unit tests (Vitest)
npm run test:coverage  # tests + coverage report

# Integration tests — hits real APIs, requires .env keys
RUN_INTEGRATION=true npm test

Endpoints de transporte HTTP

Al ejecutar con --transport http:

Referencia de errores

Licencia

MIT — ver LICENSE

Contribución

Las incidencias y PRs son bienvenidos. Por favor, lea docs/CODING_STANDARDS.md antes de enviar.