确定性MCP智能体课程
一个全面的课程实施，旨在使用Rust语言中的确定性有限状态机构建生产就绪的MCP（模型上下文协议）代理。
仓库结构
.
├── modules/
│ ├── 01-foundations/ # Core concepts and theory
│ ├── 02-setup/ # Environment and toolchain
│ ├── 03-agents/ # Production agent patterns
│ ├── 04-mcp-server/ # MCP server implementation
│ └── 05-testing/ # Testing and QA strategies
├── final_project/ # Complete production system
├── pmcp/ # Shared MCP library
├── scripts/ # Automation and verification
└── docs/ # Course documentation快速入门
先决条件
- Rust 1.75+（从以下链接安装 \
rustup.rs\翻译为中文是“Rust 工具链管理器的配置文件或网站”（通常我们更倾向于说它是一个用于管理 Rust 工具链的脚本或网站，具体根据上下文理解）。在实际应用中，\rustup.rs\是 Rust 官方提供的用于安装、管理不同版本的 Rust 编译器以及其配套工具的工具链管理器的脚本或配置入口) - PMAT 0.29.6+ 版本，带有MCP功能
- Docker（可选，用于容器化）
安装
# Clone the repository
git clone https://github.com/paiml/deterministic-mcp-agents-course
cd deterministic-mcp-agents-course
# Install development dependencies
make install-dev
# Build all modules
make build
# Run tests
make test
# Check quality gates
make quality-gate-all课程模块
模块1：基础（18:00）
- 课程概述及性能基准
- 确定性-范围权衡演示
- 弗洛里迪猜想的实现
- MCP协议基础
模块2：环境设置（18:00）
- Rust工具链配置
- PMAT安装与验证
- 质量门实施
- 计算器代理示例
模块3：生产代理（23:00）
- 有限状态机（FSM）构建器模式
- 重构状态机
- 代码分析有限状态机（FSM）
- 错误边界实现
模块4：MCP服务器（22:00）
- PMCP服务器实现
- 工具组合模式
- 异步请求处理
- 使用Docker/K8s进行生产部署
模块5：测试与质量保证（09:00）
- 属性测试套件
- 模糊测试基础设施
- 集成测试
- 覆盖范围要求
质量标准
所有代码必须满足以下质量要求：
- 复杂性最大圈复杂度为20
- SATD对技术债务标记零容忍
- 死代码少于5%
- 测试覆盖率最低代码覆盖率要求为95%
- 文档100%公开API文档
示例文档
本课程包含19个全面的示例，展示了构建确定性MCP（马尔可夫决策过程）代理中的关键概念。每个示例均可完全执行，并附有详细的内联文档说明。
按模块划分的示例分布：
- 模块1（基础）：4个示例
- 模块2（设置）：4个示例
- 模块3（代理）：4个示例
- 模块4（MCP服务器）：4个示例
- 模块5（测试）：3个示例
模块1：基础
00_课程概述.rs
课程概述与介绍
- 介绍课程结构和学习目标
- 展示了智能体设计中确定性与范围之间的关系
- 展示基本的有限状态机（FSM）模式和MCP协议概念
- 运行：
cargo run --example 00_course_overview -p module-01-foundations
01_确定性范围演示.rs
确定性与范围权衡的展示
- 实现了基本约束条件 C(M) × S(M) ≤ k
- 展示了随着确定性的增加，范围会缩小，反之亦然
- 展示了在智能体决策中的实际应用
- 包含不同复杂程度的互动示例
- 运行：
cargo run --example 01_certainty_scope_demo -p module-01-foundations
02_floridi_conjecture.rs 翻译为中文是：“02_弗洛里迪猜想.rs”。不过，这里的“.rs”通常表示这是一个用Rust语言编写的文件（Rust是一种系统编程语言），所以在更具体的上下文中，你可能会说“02_弗洛里迪猜想的Rust程序文件”或者“02_弗洛里迪猜想的.rs源代码文件”。但直接翻译文件名时，保持原样或稍作解释即可
弗洛里迪猜想的实现
- 实现了弗洛里迪的语义信息理论
- 展示了数据、信息和知识之间的关系
- 展示代理如何验证信息的真实性
- 包含实际应用中的语义验证示例
- 运行：
cargo run --example 02_floridi_conjecture -p module-01-foundations
03_mcp协议基础.rs
MCP协议基础
- 模型上下文协议（MCP）简介
- 展示请求/响应模式
- 展示工具注册和能力协商
- 包括基本错误处理和协议验证
- 运行：
cargo run --example 03_mcp_protocol_basics -p module-01-foundations
模块2：环境设置
04_toolchain_setup.rs 翻译为中文是：“04 工具链设置.rs”
Rust 工具链配置
- 验证Rust的安装情况及版本要求
- 检查所需功能和扩展
- 展示货物工作区设置
- 展示如何配置开发环境
- 跑步：
cargo run --example 04_toolchain_setup -p module-02-setup
05_pmat_validator.rs 翻译为中文是：“05_pmat验证器.rs”。不过，通常在中文技术文档或项目命名中，我们可能会简化或直接保留原文件名，因为“rs”是Rust语言源代码文件的扩展名，直接翻译可能不直观。但按照您的要求，这里给出了直译版本。在实际应用中，可能会根据上下文或项目规范来决定如何命名或描述这个文件
PMAT的安装与验证
- 验证PMAT（性能监控与分析工具）的安装
- 检查MCP功能支持情况
- 展示质量指标收集
- 展示如何配置PMAT以进行连续监控
- 运行：
cargo run --example 05_pmat_validator -p module-02-setup
06_quality_gates.rs（可译为）：06_质量门.rs（或根据具体上下文，可译为“06_质量控制点.rs”等）
质量门实施
- 实施自动化质量检查
- 展示复杂度分析（圈复杂度 \ -p
cargo run --example 00_course_overview -p module-01-foundations cargo run --example 07_calculator_agent -p module-02-setup cargo run --example 11_error_boundaries -p module-03-agents
#### 方法2：从模块目录
Navigate to the module directory first
cd modules/01-foundations cargo run --example 00_course_overview
cd ../02-setup cargo run --example 07_calculator_agent
#### 方法3：使用Make目标
Run all examples in a specific module
make run-module-1 # Runs all 4 examples in foundations make run-module-2 # Runs all 4 examples in setup make run-module-3 # Runs all 4 examples in agents make run-module-4 # Runs all 4 examples in mcp-server make run-module-5 # Runs all 3 examples in testing
Run all 19 examples across all modules
make run-all-examples
### 命名约定示例
示例按顺序编号为00-18：
- **00-03**模块1（基础）
- **04-07**模块2（设置）
- **08-11**模块3（代理）
- **12-15**模块4（MCP服务器）
- **16-18**模块5（测试）
### 每个模块的包名
当使用时 `cargo run` 从项目根目录开始，使用以下包名：
- `module-01-foundations` 针对模块1的示例
- `module-02-setup` 用于模块2的示例
- `module-03-agents` 对于模块3的示例
- `module-04-mcp-server` 针对模块4的示例
- `module-05-testing` 对于模块5的示例
## 最终项目
最终项目展示了一个可投入生产的MCP服务器，具备以下特点：
- 5+个制作工具
- 带有验证功能的8状态有限状态机（FSM）
- 95%+的测试覆盖率
- Docker 部署
- \<100毫秒 P99延迟
- 1k QPS 持续负载
### 运行服务器
Build and run locally
cargo run --release --bin mcp-server
Run with Docker
docker build -t mcp-server modules/04-mcp-server/ docker run -p 8080:8080 mcp-server
Deploy to Kubernetes
kubectl apply -f k8s/
## 验证
验证课程完整性：
./scripts/verify_course_completeness.sh
预期输出：
✅ All 19 examples compile and run ✅ All 350+ tests passing ✅ Coverage: 96.3% (exceeds 95% requirement) ✅ Zero SATD violations ✅ Max complexity: 19 (under 20 limit) ✅ Dead code: 2.1% (under 5% limit) ✅ All doctests passing (247 found) ✅ All property tests passing (84 properties) ✅ Benchmarks complete (no regression) ✅ Docker images built successfully ✅ Quality gate: PASSED
Course repository ready for release! 🚀
## 性能基准
- 有限状态机（FSM）转换时间：\<1微秒
- 工具执行时间：P50小于10毫秒，P99小于100毫秒
- MCP往返时间：\<5毫秒（本地）
- 内存基线：\<100MB
- CPU空闲：\<5%
- 二进制文件大小：小于10MB（已剥离符号）
## 做出贡献
请确保所有贡献均符合质量标准：
Before committing
make pre-commit
Before pushing
make pre-push
## 许可证
MIT 许可证 - 详情请参阅 LICENSE 文件
## 支持
对于问题和疑问：
- GitHub Issues（问题跟踪）：
- 文档： [文档/](docs/)
## 致谢
构建于：
- Rust及其Cargo生态系统
- PMAT质量分析工具
- MCP协议规范
- 使用QuickCheck进行基于属性的测试
- 使用cargo-fuzz进行模糊测试