Demo HTTP MCP Server

test-http-mcp

Servidor de Model Context Protocol (MCP) de demostración implementado en Python usando el paquete http-mcp. Puede ejecutarse a través de HTTP (Starlette/Uvicorn) o stdio, exponiendo herramientas y prompts de ejemplo a cualquier cliente compatible con MCP. El proyecto incluye un frontend en React que proporciona una interfaz de chat para consultar vulnerabilidades a través de la NVD (National Vulnerability Database).

Estructura del proyecto

test-http-mcp/
├── backend/                 # Python backend (FastAPI + MCP server)
│   ├── app/                 # Application source code
│   │   ├── app.py           # FastAPI app, routes, MCP mount
│   │   ├── main.py          # Entry points (HTTP / stdio)
│   │   ├── agen_memory.py   # SQLite message persistence
│   │   ├── config.py        # Settings via pydantic-settings
│   │   ├── auth0/           # Auth0 integration
│   │   │   ├── __init__.py  # JWT token validator
│   │   │   └── client_store.py # Dynamic client registration (RFC 7591)
│   │   ├── tools/           # MCP tools (CPE/CVE search via NVD)
│   │   └── prompts/         # MCP prompt templates
│   ├── pyproject.toml       # Python deps & scripts
│   ├── uv.lock              # Locked dependencies
│   ├── ruff.toml            # Linter config
│   ├── mypy.ini             # Type-checker config
│   └── .envrc               # direnv auto-activation
├── frontend/                # React + TypeScript frontend (Vite)
│   ├── src/
│   │   ├── components/      # ChatApp, ChatInput, MessageList, MessageBubble
│   │   ├── api.ts           # API client (fetch history, stream messages)
│   │   ├── types.ts         # Shared TypeScript types
│   │   ├── App.tsx          # Root component
│   │   └── App.css          # Styles
│   ├── vite.config.ts       # Vite config with dev proxy
│   └── package.json         # Node dependencies
├── AGENTS.md
├── LICENSE
└── README.md

Autenticación (Auth0)

El endpoint MCP (/mcp/) está protegido con autenticación OAuth2 de Auth0. Las herramientas requieren que los ámbitos (tool:search_cpe, tool:search_cve) estén presentes en el token de acceso.

Variables de entorno requeridas

Colóquelas en backend/.env (ignorado por git).

Estructura de montaje de la aplicación

Nota: Los endpoints de chat están intencionalmente sin autenticar para el desarrollo local. Agregue autenticación antes de exponerlos fuera de localhost.

Requisitos

• Python 3.13

• Node.js 18+ y npm

• uv (recomendado) o pip

Instalación

Backend (usando uv):

cd backend
uv run python -V            # creates a venv and syncs deps from pyproject

Backend (usando pip):

cd backend
python3.13 -m venv .venv
source .venv/bin/activate
pip install .

Frontend:

cd frontend
npm install

Ejecución

Desarrollo (frontend + backend por separado)

Inicie el backend:

cd backend
uv run run-app
# → API on http://localhost:8000
# → MCP endpoint on http://localhost:8000/mcp/

Inicie el servidor de desarrollo del frontend (en una terminal separada):

cd frontend
npm run dev
# → UI on http://localhost:5173 (proxies /api/* → backend)

Producción (el backend sirve el frontend compilado)

Compile el frontend e inicie el backend:

cd frontend && npm run build && cd ..
cd backend && uv run run-app
# → Everything on http://localhost:8000

Ejecución (modo stdio)

Uso con Cursor u otros clientes MCP

Con Auth0 habilitado, los clientes deben obtener un token de acceso OAuth2. El servidor admite RFC 7591 Dynamic Client Registration en /register, por lo que los clientes MCP que implementan la especificación de autenticación se registrarán automáticamente.

Ejemplo de .cursor/mcp.json para modo HTTP:

{
  "mcpServers": {
    "test-http-mcp": {
      "type": "http",
      "url": "http://localhost:8000/mcp/"
    }
  }
}

Uso con Gemini:

{
  "mcpServers": {
    "test": {
      "httpUrl": "http://localhost:8000/mcp/",
      "timeout": 5000
    }
  }
}

Ejemplo de entrada en .cursor/mcp.json para conectar a través de stdio:

{
  "mcpServers": {
    "test_studio": {
      "command": "uv",
      "args": ["run", "--project", "backend", "run-stdio"],
      "env": { "AUTHORIZATION_TOKEN": "Bearer TEST_TOKEN" }
    }
  }
}

Lo que expone este servidor

• Herramientas (ver backend/app/tools/):

  • search_cpe(product, version, vendor) — buscar Common Platform Enumerations a través de NVD

  • search_cve(cpe_name) — buscar Common Vulnerabilities and Exposures para un CPE dado

• Prompts (ver backend/app/prompts/):

  • sync_nvd_search(dependency, version) — prompt simple de búsqueda de vulnerabilidades

  • async_nvd_search(dependency, version) — prompt avanzado con datos CVE pre-obtenidos

Scripts del proyecto

Se definen dos puntos de entrada de consola en backend/pyproject.toml:

• run-app → app.main:run_http

• run-stdio → app.main:run_stdio

• run-app-local → app.app:main (con recarga automática)

Desarrollo

Tareas comunes (ejecutar desde el directorio backend/):

uv run ruff check .           # lint
uv run mypy .                 # type check
uv run pytest                 # tests
uv run mdformat .             # format markdown

Tareas del frontend (ejecutar desde el directorio frontend/):

npm run dev                   # start dev server
npm run build                 # production build
npm run lint                  # lint with ESLint
npx tsc --noEmit              # type check

Notas de implementación

• La aplicación ASGI raíz es una aplicación MCP protegida por Auth0 creada por auth_mcp, que monta la sub-aplicación FastAPI en /api.

• El endpoint MCP en /mcp/ requiere un token Bearer de Auth0 válido con los ámbitos de herramienta apropiados.

• El registro dinámico de clientes en /register actúa como proxy hacia una aplicación Auth0 pre-creada, actualizando sus URLs de callback permitidas. Las URIs de redirección se validan (se requiere HTTPS; HTTP solo se permite para localhost).

• La interfaz de chat utiliza pydantic-ai con un agente Ollama que puede llamar a herramientas MCP para buscar vulnerabilidades.

• El historial de chat se persiste en una base de datos SQLite local a través de agen_memory.py.

• El frontend de React transmite respuestas como JSON delimitado por nuevas líneas y renderiza markdown con la biblioteca marked.

• En producción, el backend sirve el frontend compilado desde frontend/dist/ con enrutamiento de respaldo SPA (protegido contra recorrido de rutas).

• En desarrollo, Vite actúa como proxy para las solicitudes /api/* al backend en el puerto 8000.

Licencia

MIT — ver LICENSE.