AI导哈

FastAPI + MCP 集成演示

一个演示 FastAPI 与 MCP 共享代码库与业务逻辑的 AI-ready API 项目，以产品 CRUD 为例，支持 REST、gRPC、GraphQL 与 A2A 智能体调用。

  • by kalaiguna
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 kalaiguna/fastpoc-mcp-api

使用说明

FastPOC - FastAPI + MCP Integration POC

A demo repository for building AI-ready APIs. The goal is to explore and showcase how a REST API (FastAPI) and an MCP Server (Model Context Protocol) can share the same codebase and business logic — and to progressively extend it with other emerging concepts and new AI integration patterns.

Current focus: Python FastAPI + MCP with a simple Product CRUD domain as the working example.

Project Structure

fastpoc/
├── python/          # Python implementation using FastAPI + MCP
│   ├── app/         # Application modules (REST, MCP, gRPC, GraphQL, agents)
│   ├── protos/      # gRPC service definitions (.proto)
│   ├── main.py      # FastAPI entry point
│   ├── mcp_entry.py # MCP server entry point
│   ├── grpc_entry.py# gRPC server entry point
│   └── README.md    # Python-specific documentation
├── examples/        # Standalone client scripts (A2A flow demo)
├── docs/            # Architecture and backlog
└── README.md        # This file

Implementation

Python (FastAPI + MCP) ✅ Production-Ready

  • Location: python/
  • Technologies: FastAPI, MCP (Model Context Protocol), Pydantic, SQLite
  • Features:
    • REST API with Swagger UI at /api/v1/docs
    • Versioned API endpoints (/api/v1/products)
    • MCP Server for AI tool integration
    • gRPC server with typed contracts and server-streaming
    • GraphQL endpoint with GraphiQL explorer at /graphql
    • Shared codebase across REST, MCP, gRPC, and GraphQL
    • SQLite database with automatic initialization
    • Full CRUD operations with input validation
    • Health check endpoints (/health, /ready)
    • API key authentication (X-API-Key header)
    • Rate limiting (60/min reads, 30/min writes)
    • Structured error responses ({"error": {"code": "...", "message": "..."}})
    • A2A agents: PricingAgent and ProductAgent with sync, async, and streaming endpoints
    • Agent Cards (/.well-known/agent.json) for service discovery
    • Async task lifecycle: submit → poll → result
    • SSE streaming: live progress events via text/event-stream
    • Docker support with health checks
    • GitHub Actions CI
    • Comprehensive test suite (53 tests)
    • Environment-based configuration
    • Structured logging

See python/README.md for detailed instructions.

Quick Start

Using Docker (Recommended)

cd python
docker-compose up --build

Access the API at http://localhost:8081 and Swagger UI at http://localhost:8081/api/v1/docs.

Local Development

cd python
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
python main.py

Configuration

Configure via environment variables or .env file:

  • PORT - Server port (default: 8081)
  • HOST - Server host (default: 0.0.0.0)
  • API_VERSION - API version prefix (default: v1)
  • DB_PATH - SQLite database path (default: auto-detected)
  • API_KEY - API key for protected endpoints (default: dev-key-changeme)
  • PRICING_AGENT_URL - Base URL of the PricingAgent; defaults to the same host (same-process call)

See .env.example for reference.

Exploring the Layers

Start the server first:

cd python && python main.py

REST API

  • Open http://localhost:8081/api/v1/docs — Swagger UI with all CRUD endpoints
  • Click Authorize, enter dev-key-changeme, and all protected endpoints unlock for interactive testing

MCP

  • Run python mcp_entry.py — starts the MCP server in stdio mode
  • Connect via Claude Desktop using the config in python/README.md
  • The five product tools (list_products, get_product, create_product, update_product, delete_product) appear as AI assistant tools

gRPC

  • Run python grpc_entry.py — starts the gRPC server on port 50051
  • Run python examples/grpc_client.py — unary CRUD calls plus the server-streaming StreamPricingAnalysis
  • Contract defined in python/protos/product.proto; regenerate stubs with python scripts/gen_grpc.py

GraphQL

  • With the API server running, open http://localhost:8081/graphql — the GraphiQL explorer UI
  • Set X-API-Key: dev-key-changeme in GraphiQL's headers panel, then run a query like { products { id name price } }
  • Schema (Query + Mutation) defined in python/app/graphql_schema.py

A2A (Agent-to-Agent)

  • Open http://localhost:8081/.well-known/agent.json in a browser — the Agent Card describes what agents exist, what they can do, and where to call them
  • Run python examples/a2a_client.py — walks through the full flow with printed output: discover → submit → poll → result
  • Or call agents directly in Swagger: POST /api/v1/agents/product/run with {"product_id": 1}
  • For live progress: POST /api/v1/agents/product/stream — returns text/event-stream with working events then the final completed result

Reading the code

  • CRUD logic: python/app/business.py → api.py
  • MCP tools: python/app/mcp.py
  • gRPC servicers: python/app/grpc_server.py (contract in python/protos/product.proto)
  • GraphQL schema: python/app/graphql_schema.py
  • A2A agents: python/app/agents/router.py, pricing.py, cards.py
  • See Architecture for design decisions and how the layers relate

Documentation

  • Architecture - design decisions, module structure, and how to extend the project
  • LLM Integration - connect an LLM to the service via MCP Inspector, Claude Desktop, or Gemini API
  • Backlog - planned features and improvements, prioritised

Testing

cd python
pytest

相关 MCP