Demo HTTP MCP Server

test-http-mcp

Демонстрационный сервер протокола контекста модели (MCP), реализованный на Python с использованием пакета http-mcp. Он может работать через HTTP (Starlette/Uvicorn) или через stdio, предоставляя примеры инструментов (Tools) и подсказок (Prompts) любому MCP-совместимому клиенту. Проект включает в себя фронтенд на React, который предоставляет чат-интерфейс для поиска уязвимостей через NVD (Национальная база данных уязвимостей).

Структура проекта

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

Аутентификация (Auth0)

MCP-эндпоинт (/mcp/) защищен с помощью аутентификации Auth0 OAuth2. Для инструментов требуются области видимости (scopes) (tool:search_cpe, tool:search_cve), которые должны присутствовать в токене доступа.

Необходимые переменные окружения

Разместите их в backend/.env (файл игнорируется git).

Структура монтирования приложения

Примечание: Эндпоинты чата намеренно не защищены для локальной разработки. Добавьте аутентификацию перед тем, как открывать доступ за пределами localhost.

Требования

• Python 3.13

• Node.js 18+ и npm

• uv (рекомендуется) или pip

Установка

Бэкенд (с использованием uv):

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

Бэкенд (с использованием pip):

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

Фронтенд:

cd frontend
npm install

Запуск

Разработка (фронтенд + бэкенд отдельно)

Запуск бэкенда:

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

Запуск сервера разработки фронтенда (в отдельном терминале):

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

Продакшн (бэкенд обслуживает собранный фронтенд)

Сборка фронтенда и запуск бэкенда:

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

Запуск (режим stdio)

Использование с Cursor или другими MCP-клиентами

При включенном Auth0 клиенты должны получить токен доступа OAuth2. Сервер поддерживает динамическую регистрацию клиентов RFC 7591 по адресу /register, поэтому MCP-клиенты, реализующие спецификацию аутентификации, будут регистрироваться автоматически.

Пример .cursor/mcp.json для режима HTTP:

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

Использование с Gemini:

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

Пример записи .cursor/mcp.json для подключения через stdio:

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

Что предоставляет этот сервер

• Инструменты (см. backend/app/tools/):

  • search_cpe(product, version, vendor) — поиск перечислений общих платформ (CPE) через NVD

  • search_cve(cpe_name) — поиск общих уязвимостей и рисков (CVE) для заданного CPE

• Подсказки (см. backend/app/prompts/):

  • sync_nvd_search(dependency, version) — простая подсказка для поиска уязвимостей

  • async_nvd_search(dependency, version) — расширенная подсказка с предварительно полученными данными CVE

Скрипты проекта

В backend/pyproject.toml определены две точки входа в консоль:

• run-app → app.main:run_http

• run-stdio → app.main:run_stdio

• run-app-local → app.app:main (с автоматической перезагрузкой)

Разработка

Общие задачи (запускаются из директории backend/):

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

Задачи фронтенда (запускаются из директории frontend/):

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

Примечания по реализации

• Корневое приложение ASGI — это защищенное Auth0 MCP-приложение, созданное с помощью auth_mcp, которое монтирует подприложение FastAPI по адресу /api.

• MCP-эндпоинт /mcp/ требует действительный токен Auth0 Bearer с соответствующими областями видимости инструментов.

• Динамическая регистрация клиентов по адресу /register проксирует запросы к предварительно созданному приложению Auth0, обновляя его разрешенные URL-адреса обратного вызова. URI перенаправления проверяются (требуется HTTPS; HTTP разрешен только для localhost).

• Чат-интерфейс использует pydantic-ai с агентом Ollama, который может вызывать инструменты MCP для поиска уязвимостей.

• История чата сохраняется в локальной базе данных SQLite через agen_memory.py.

• Фронтенд на React передает ответы в виде JSON, разделенного символами новой строки, и отображает Markdown с помощью библиотеки marked.

• В продакшене бэкенд обслуживает собранный фронтенд из frontend/dist/ с резервной маршрутизацией SPA (защищено от обхода путей).

• В режиме разработки Vite проксирует запросы /api/* на бэкенд на порт 8000.

Лицензия

MIT — см. LICENSE.