fakemcp 0.1.0

Intelligent MCP server simulator for testing AI agents with scenario-driven mock data generation

FakeMCP

FakeMCP 是一个智能的 MCP (Model Context Protocol) 服务器模拟器，用于在测试 AI Agent 时模拟其他 MCP 服务器的行为。它能够根据用户提供的场景描述和真实 MCP 服务器配置，生成符合逻辑的模拟数据，从而帮助开发者测试各种复杂场景而无需依赖真实的外部服务。

功能特性

• 🎭 角色驱动: 将场景中的实体（城市、服务器、用户等）抽象为"角色"，每个角色有独立的状态和行为
• 📝 剧本模式: 场景描述就像电影剧本，定义角色在特定情境下的表现
• 🔗 因果关系: 支持跨角色的因果关系，模拟复杂的系统交互场景
• 📊 剧情图: 构建和验证剧情的时间线，确保数据的逻辑一致性
• 🤖 AI 协作: 通过 guide 工具返回提示词，让 AI IDE 的 Agent 自动化地帮助构建场景
• 📚 真实学习: 从真实 MCP 服务器获取 Schema 和示例数据，确保模拟数据的真实性
• 💾 场景持久化: 支持保存和加载场景配置，方便重复使用测试场景

快速开始

安装

# 基础安装
pip install -e .

# 开发安装（包含测试依赖）
pip install -e ".[dev]"

启动服务器

fakemcp

服务器将通过标准输入/输出与 AI IDE 通信（MCP 协议）。

基本使用流程

1. 初始化场景: 使用 guide 工具获取引导提示
2. 添加目标 MCP: 使用 add_target_mcp 添加要模拟的 MCP 服务器
3. 设置场景描述: 使用 set_scenario 描述测试场景
4. 配置角色: 使用 add_actor_config 为角色添加场景配置
5. 构建剧情: 使用 add_causality_relation 建立因果关系
6. 生成数据: 使用 generate_mock_data 生成模拟数据
7. 验证数据: 使用 validate_mock_data 验证数据合理性
8. 保存场景: 使用 save_scenario 保存配置供后续使用

详细示例请参考 EXAMPLES.md。

核心概念

场景 (Scenario)

场景是测试的上下文环境，包含场景描述、涉及的目标 MCP 服务器、角色配置等信息。

角色 (Actor)

角色是场景中的实体，如服务器、城市、用户等。每个角色有独立的状态和行为配置，支持层级关系（如"南山区"属于"深圳"）。

目标 MCP (Target MCP)

需要被 FakeMCP 模拟的真实 MCP 服务器。FakeMCP 会从目标 MCP 获取 Schema 和示例数据，用于生成符合格式的模拟数据。

因果关系 (Causality Relation)

定义角色之间的因果关系，如"服务 A 的错误导致服务 B 的内存泄露"。FakeMCP 会根据因果关系生成符合逻辑的数据。

剧情图 (Plot Graph)

基于因果关系构建的有向图，表示事件的时间线和依赖关系。用于指导数据生成，确保数据的逻辑一致性。

可用工具

FakeMCP 通过 MCP 协议暴露以下工具：

工作流引导

• guide: 获取当前阶段的引导提示和下一步操作建议

场景管理

• set_scenario: 设置场景描述
• add_target_mcp: 添加目标 MCP 服务器
• get_scenario_status: 获取当前场景状态

角色管理

• add_actor_config: 为角色添加场景配置
• remove_actor_config: 删除角色配置
• list_actors: 列出所有角色

剧情管理

• request_plot_expansion: 请求剧情扩展（返回提示词给 AI IDE）
• add_causality_relation: 添加因果关系
• build_plot_graph: 构建剧情图
• validate_plot_consistency: 验证剧情一致性

数据操作

• fetch_real_data: 从真实 MCP 服务器获取示例数据
• generate_mock_data: 生成模拟数据
• validate_mock_data: 验证模拟数据的合理性

场景持久化

• save_scenario: 保存场景配置到文件
• load_scenario: 从文件加载场景配置

详细的工具参数和返回值请参考设计文档。

项目结构

fakemcp/
├── src/
│   └── fakemcp/
│       ├── __init__.py              # 包初始化
│       ├── main.py                  # 主入口
│       ├── config.py                # 配置管理
│       ├── models.py                # 数据模型
│       ├── database.py              # 数据库层
│       ├── mcp_server.py            # MCP 协议层
│       ├── scenario_manager.py      # 场景管理器
│       ├── actor_manager.py         # 角色管理器
│       ├── target_mcp_analyzer.py   # 目标 MCP 分析器
│       ├── data_generator.py        # 数据生成器
│       ├── plot_manager.py          # 剧情管理器
│       ├── validation_service.py    # 验证服务
│       ├── workflow_guide.py        # 工作流引导
│       ├── errors.py                # 错误定义
│       ├── logger.py                # 日志配置
│       └── tools/                   # MCP 工具实现
│           ├── guide_tool.py        # 引导工具
│           ├── scenario_tools.py    # 场景管理工具
│           ├── actor_tools.py       # 角色管理工具
│           ├── plot_tools.py        # 剧情管理工具
│           ├── data_tools.py        # 数据操作工具
│           └── persistence_tools.py # 持久化工具
├── tests/                           # 测试目录
├── examples/                        # 示例代码
├── .kiro/specs/fake-mcp-server/    # 设计文档
├── pyproject.toml                   # 项目配置
├── README.md                        # 项目文档
└── EXAMPLES.md                      # 使用示例

架构设计

FakeMCP 采用分层架构：

1. MCP 协议层: 处理 MCP 协议的握手、工具注册和调用路由
2. 工具层: 实现各种 MCP 工具的处理逻辑
3. 核心服务层: 提供场景管理、角色管理、数据生成等核心功能
4. 存储层: 持久化场景配置、角色状态、Schema 缓存等数据

详细的架构设计请参考 .kiro/specs/fake-mcp-server/design.md。

开发

运行测试

# 运行所有测试
pytest

# 运行特定测试文件
pytest tests/test_scenario_manager.py

# 运行测试并显示覆盖率
pytest --cov=fakemcp

代码风格

项目使用 Python 标准代码风格，建议使用 black 和 isort 进行代码格式化。

依赖

• Python >= 3.10
• mcp >= 0.1.0
• httpx >= 0.24.0
• jsonschema >= 4.17.0
• pyyaml >= 6.0

贡献

欢迎提交 Issue 和 Pull Request！

许可证

MIT

相关资源

• MCP 协议规范
• 设计文档
• 需求文档
• 使用示例