test-http-mcp

http-mcp 패키지를 사용하여 Python으로 구현된 데모 MCP(Model Context Protocol) 서버입니다. HTTP(Starlette/Uvicorn) 또는 stdio를 통해 실행할 수 있으며, MCP를 지원하는 모든 클라이언트에 예제 도구와 프롬프트를 노출합니다. 이 프로젝트에는 NVD(National Vulnerability Database)를 통해 취약점을 쿼리할 수 있는 채팅 인터페이스를 제공하는 React 프론트엔드가 포함되어 있습니다.

Chat UI

프로젝트 구조

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
│   │   ├── 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

요구 사항

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 클라이언트와 함께 사용

HTTP 모드용 예제 .cursor/mcp.json:

{
  "mcpServers": {
    "test-http-mcp": {
      "type": "http",
      "url": "http://localhost:8000/mcp/",
      "headers": {
        "Authorization": "Bearer $TEST_TOKEN"
      }
    }
  }
}

Gemini와 함께 사용:

{
  "mcpServers": {
    "test": {
      "httpUrl": "http://localhost:8000/mcp/",
      "timeout": 5000,
      "headers": {
        "Authorization": "Bearer TEST_TOKEN"
      }
    }
  }
}

stdio를 통해 연결하기 위한 예제 .cursor/mcp.json 항목:

{
  "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) — NVD를 통해 CPE(Common Platform Enumerations) 검색
- search_cve(cpe_name) — 주어진 CPE에 대한 CVE(Common Vulnerabilities and Exposures) 검색
프롬프트 (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

구현 참고 사항

FastAPI 앱은 backend/app/app.py에 정의되어 있으며 /mcp 경로에 http_mcp.server.MCPServer를 마운트합니다.
채팅 인터페이스는 MCP 도구를 호출하여 취약점을 검색할 수 있는 Gemini 에이전트와 함께 pydantic-ai를 사용합니다.
채팅 기록은 agen_memory.py를 통해 로컬 SQLite 데이터베이스에 유지됩니다.
React 프론트엔드는 줄바꿈으로 구분된 JSON으로 응답을 스트리밍하고 marked 라이브러리를 사용하여 마크다운을 렌더링합니다.
프로덕션 환경에서 백엔드는 SPA 폴백 라우팅과 함께 frontend/dist/에서 빌드된 프론트엔드를 서빙합니다.
개발 환경에서 Vite는 /api/* 요청을 8000번 포트의 백엔드로 프록시합니다.

라이선스

MIT — LICENSE 참조.

Demo HTTP MCP Server

test-http-mcp

프로젝트 구조

요구 사항

설치

실행

개발 (프론트엔드 + 백엔드 별도 실행)

프로덕션 (백엔드가 빌드된 프론트엔드를 서빙)

실행 (stdio 모드)

Cursor 또는 기타 MCP 클라이언트와 함께 사용

이 서버가 노출하는 기능

프로젝트 스크립트

개발

구현 참고 사항

라이선스

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API