快速入门指南：FastMCP 应用程序

项目架构

该应用程序基于 FastMCP 构建，包含以下核心组件：

• MCP 服务器：负责处理工具调用和资源请求
• FastAPI 接口：提供 RESTful API 服务
• LLM Agent：实现智能自动化功能

目录结构

项目根目录/
├── app/
│   ├── mcp_server/
│   │   ├── simple.py          # MCP 服务器核心逻辑
│   │   └── run.py             # 服务器运行配置
│   ├── llm/
│   │   ├── base.py            # LLM 基类定义
│   │   └── openai.py           # OpenAI 实现
│   └── api/
│       ├── tools.py           # 工具管理模块
│       ├── resources.py        # 资源管理模块
│       └── agent.py            # Agent 模块
└── README.md                  # 项目文档

核心工作流程

API 模式

1. 启动 MCP 服务器：

python main.py --mode mcp

2. 启动 FastAPI 服务端口，默认连接到 MCP 服务器：

python main.py --mode api

直接运行 MCP 服务器

# 使用 SSE 运输，默认绑定 localhost:8001
python main.py --mode mcp

# 使用标准输入输出运输
python main.py --mode mcp --mcp-transport stdio

功能特性

• 模块化设计：松耦合架构，便于功能扩展
• 双运行模式：
  • API 模式：提供 RESTful 接口服务
  • MCP 直接运行：支持直接连接其他客户端
• 工具链支持：可插拔的工具体系结构
• 资源管理：内置资源加载和访问控制机制
• LLM 集成：支持多种大语言模型
• 热重载功能：开发环境下的自动代码重启

安装指南

克隆仓库

git clone your_repository_url
cd your_project_directory

依赖安装

pip install fastapi uvicorn openai

环境变量设置

export OPENAI_API_KEY="your_api_key_here"

使用说明

运行服务：

# 启动 MCP 服务器
python main.py --mode mcp

# 启动 API 服务，默认绑定 localhost:8080，连接到 MCP 服务器
uvicorn app.api.app:app --reload

API 接口文档

访问地址：http://localhost:8080/docs

工具接口 (/api/tools)

• GET /：获取所有可用工具列表
• POST /{tool_name}：调用特定工具，支持参数传递和 LLM 集成

资源接口 (/api/resources)

• GET /：列出所有资源 URI 及类型
• GET /{resource_path:path}：获取指定资源内容

Agent 接口 (/api/agent)

• POST /process：通过 LLM 自动处理用户请求，支持工具调用

扩展开发

新增工具

1. 在 simple.py 中继承 BaseMCPServer
2. 使用 @self.mcp.tool() 装饰器注册新工具
3. 实现具体业务逻辑

示例：

from app.core.mcp import BaseMCPServer

class MyMCP(BaseMCPServer):
    def my_tool(self, input: str) -> str:
        return f"Processed: {input}"

新增 LLM 提供商

1. 继承 LLMBase 类并实现具体逻辑
2. 在 run.py 中注册新提供商

示例：

from app.llm.base import LLMBase

class MyLLM(LLMBase):
    def generate(self, prompt: str) -> str:
        # 实现具体的生成逻辑

开发注意事项

• 代码风格：遵循 PEP8 规范
• 日志记录：使用标准库 logging 模块
• 异常处理：统一的错误捕捉和处理机制
• 依赖注入：推荐使用 pydantic 或 injector
• 单元测试：建议为每个模块编写自动化测试

项目目标

• 提供一个可扩展的 MCP 实现框架
• 搭建一个功能完善的 API 平台
• 实现 LLM 能力与工具链的深度集成

贡献指南

欢迎社区贡献代码和文档，共同完善这个开源项目！

提交规范

1. 遵循 CONTRIBUTING.md 文件
2. 为新功能添加对应文档
3. 提交 PR 前通过所有测试用例