Serve7 MCP Connector Library

Herramientas reutilizables de MCP para Amazon Connect AI Agents y Bedrock AgentCore. Siete conectores genéricos —consulta de cliente, creación de un ticket de soporte, comprobación del estado del ticket, programación de una cita, actualización de un registro de CRM, recuperación de conocimiento y creación de una tarea—, construidos aquí una sola vez y reutilizados en todas las interacciones con los clientes de Serve7, en lugar de tener que conectarlos desde cero en cada proyecto.

Este es el proyecto n.º 6 de la lista de ideas de prácticas de otoño de 2026 («Serve7 MCP Connector Library»). Es una primera versión funcional: cada conector funciona hoy de extremo a extremo contra un backend simulado en memoria (sin cuenta de AWS, sin CRM real y sin credenciales para probarlo), con un punto de extensión limpio para poder sustituirlo por un backend real más adelante.

Por qué un adaptador y no una integración directa

La lógica de negocio de cada conector (validación de esquema, qué se considera un error, qué campos entran y salen) se sitúa en src/connectors/*.ts y nunca accede directamente un SDK de backend concreto. En su lugar, llama a una de las cinco pequeñas interfaces de src/adapters/types.ts — CrmAdapter, TicketingAdapter, SchedulingAdapter, KnowledgeAdapter, TaskAdapter. Hoy todas están implementadas en memoria (src/adapters/mock.ts). Mañana, conectar un backend real de Salesforce/ServiceNow/Connect-Cases/Bedrock-Knowledge-Base implica escribir una nueva clase de adaptador y cambiar una única sentencia switch (src/adapters/index.ts): cero cambios en el código del conector, en sus pruebas o en las definiciones de herramientas MCP que ve un agente. Consulta docs/adding-a-real-adapter.md.

MCP client (Claude Desktop, Bedrock AgentCore, ...)
        │  tool call: customer_lookup({ customerId: "cust-1001" })
        ▼
src/server.ts (stdio) or src/http-server.ts (deployed)
        │  registers every connector as an MCP tool
        ▼
src/connectors/customer-lookup.ts
        │  validates input (zod), calls adapters.crm.lookupCustomer(...)
        ▼
src/adapters/index.ts  →  mock.ts today, a real adapter later

Related MCP server: Runtime MCP Server

Estructura del proyecto

src/
  connectors/       one file per MCP tool — schema + business logic only
  adapters/          the CRM/ticketing/scheduling/knowledge/task interfaces,
                      plus the in-memory mock implementations
  mock-data/         seed data the mock adapters serve
  mcp-server-factory.ts   registers every connector on an McpServer instance
  server.ts          stdio entrypoint (local dev, Claude Desktop, Claude Code)
  http-server.ts      Streamable-HTTP entrypoint (deployed, e.g. behind Lambda)
tests/               one test file per connector + a registry sanity test
deploy/              Dockerfile + AWS SAM template for a Lambda deployment
docs/                per-connector reference + how to add a real adapter

Ejecutarlo localmente

npm install
npm test              # 29 tests, all against the mock adapters
npm run typecheck      # strict TypeScript, zero `any` in connector code
npm start              # stdio MCP server — Ctrl+C to stop
npm run start:http      # HTTP MCP server on :8080 (curl http://localhost:8080/health)
npm run smoke           # real MCP client over stdio, calls all 7 tools end to end
npm run smoke:http      # same, over HTTP — start:http must be running first

Conectarlo en Claude Desktop / Claude Code

Apunta un cliente MCP al servidor stdio, p. ej., en claude_desktop_config.json de Claude Desktop:

{
  "mcpServers": {
    "serve7-connectors": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/serve7-mcp-connectors/src/server.ts"]
    }
  }
}

Luego pregúntale algo como «busca al cliente cust-1001» o «¿qué artículos de conocimiento tenemos sobre los avisos de cierre de emergencia?» — llamará a customer_lookup / retrieve_knowledge con los datos simulados.

Desplegarlo para un uso real (p. ej., desde Bedrock AgentCore)

Consulta deploy/README.md: crea una Lambda basada en imagen de contenedor detrás de una Function URL autenticada con IAM mediante sam deploy.

Añadir un octavo conector

1. Crea src/connectors/my-new-tool.ts con defineConnector(): copia la forma de uno existente, p. ej., create-task.ts.

2. Añádelo al array CONNECTORS en src/connectors/index.ts.

3. Añade un archivo de prueba en tests/.

4. Documéntalo en docs/connectors.md.

server.ts, http-server.ts y la prueba del registro lo detectan automáticamente: no hay que tocar nada más.

Qué queda deliberadamente fuera del alcance de esta primera versión

Según el encargo original del proyecto, cada conector debía cubrir también el enfoque de autenticación (hecho, en la capa de adaptador), una plantilla de despliegue (hecho, deploy/) y documentación (hecho, docs/) — todo ello se ha incluido. Aún no está construido, y merece una continuación rápida: un adaptador real para al menos un backend (para que esto deje de ser todo simulado) y conectar un agente de Bedrock AgentCore real para que lo llame a través del endpoint HTTP desplegado, de extremo a extremo.