fakemcp 0.1.0
Intelligent MCP server simulator for testing AI agents with scenario-driven mock data generation
Requires Python: >=3.10
Keywords: mcp, testing, mock, simulator, ai-agent

# FakeMCP

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

## 功能特性

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

## 快速开始

### 安装

```bash
# 基础安装
pip install -e .

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

### 启动服务器

```bash
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](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`。

## 开发

### 运行测试

```bash
# 运行所有测试
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 协议规范](https://modelcontextprotocol.io/)
- [设计文档](.kiro/specs/fake-mcp-server/design.md)
- [需求文档](.kiro/specs/fake-mcp-server/requirements.md)
- [使用示例](EXAMPLES.md)