agentic-mcp-gateway

Model Context Protocol (MCP)

herramientas en un bucle agéntico para trabajo de operaciones: recuperar políticas de una base de conocimiento local (RAG), buscar pagos simulados y abrir tickets — la misma forma que los copilotos de producción que se sitúan frente a las APIs de banca central / operaciones, sin ningún código propietario.

Este repositorio es software de demostración original de Md Tanvir Alam. Utiliza únicamente conceptos genéricos de pagos, KYC y mensajería interbancaria.

Related MCP server: LightsOut

Arquitectura

flowchart LR
  subgraph Client
    Recruiter["CLI / curl / MCP client"]
  end

  subgraph HTTP["Optional FastAPI"]
    Chat["POST /chat"]
    Health["GET /health"]
  end

  subgraph Agent["Agent loop"]
    LLM["LLM or FakeLLM stub"]
    ReAct["ReAct planner"]
  end

  subgraph MCP["MCP server"]
    T1["retrieve_docs"]
    T2["search_payments"]
    T3["create_ticket"]
  end

  subgraph Data
    KB["Markdown KB + hash embeddings"]
    SQLite["SQLite mock ledger / tickets"]
  end

  Recruiter --> Chat
  Recruiter --> MCP
  Chat --> ReAct
  ReAct --> LLM
  ReAct --> T1 & T2 & T3
  MCP --> T1 & T2 & T3
  T1 --> KB
  T2 --> SQLite
  T3 --> SQLite

El servidor MCP y el agente HTTP comparten un único registro de herramientas. Ese es el patrón de producción: exponer las mismas capacidades tipadas sobre stdio/SSE para agentes de IDE y sobre HTTP para una interfaz de producto.

Inicio rápido

Python 3.11+ (3.12/3.13 también funciona). No se requiere clave API.

python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# tests — FakeLLM, hash embeddings, in-memory SQLite
pytest -q

# HTTP demo
cp .env.example .env
PYTHONPATH=src python -m uvicorn agentic_mcp_gateway.http_app:app --port 8080

Prueba una sesión:

curl -s localhost:8080/health
curl -s localhost:8080/chat -H 'content-type: application/json' \
  -d '{"message":"Find payment PMT-1002 and open a ticket if it is stuck"}'

MCP stdio (para clientes tipo Claude Desktop / Cursor):

PYTHONPATH=src python -m agentic_mcp_gateway.mcp_server

Docker:

docker compose up --build
# then the same curl against localhost:8080

Cómo se mapean las herramientas MCP a producción

El agente es un pequeño bucle ReAct: pensar → elegir una herramienta → observar → repetir, y luego responder. Con LLM_PROVIDER=fake el planificador es determinista, por lo que CI nunca necesita OpenAI. Establece LLM_PROVIDER=llm y OPENAI_API_KEY para cambiar a un modelo de chat real; los contratos de herramientas permanecen idénticos.

Los embeddings por defecto son n-gramas de caracteres con hash (coseno numpy). Ese es un respaldo de demostración documentado: cambia HashingEmbedder por un sentence-transformer o una API de embeddings de un proveedor sin modificar la interfaz del recuperador.

Estructura del proyecto

src/agentic_mcp_gateway/   package
  tools/                   retrieve / payments / tickets
  agent.py                 ReAct + FakeLLM
  mcp_server.py            MCP stdio server
  http_app.py              FastAPI /chat
docs/kb/                   sample ops knowledge
tests/                     tool registry, RAG, mocked agent turn

Autor

Md Tanvir Alam — github.com/tanvir-ux

Licencia MIT. No afiliado a ningún banco ni proveedor de banca central.