MCP代理手册
使用MCP构建AI代理：从本地原型到企业部署🛠️
______________________________________________________________________
1.TL；博士
通过这本书，你将构建：
“一个从电子表格中读取销售数据、在MATLAB中运行高级分析并生成精美报告（Markdown→ PPT/Word/静态站点），可通过MCP工具从笔记本电脑部署到云端。”
本书涵盖：
- 启动 *代理循环* （Claude Desktop/带有工具调用的自定义OpenAI响应客户端），
- 开发中 *MCP服务器* 向代理提供工具（电子表格、分析、报告），
- 部署代理+工具 *生产* （FastMCP云、MATLAB生产服务器、渲染、GitHub操作）。
______________________________________________________________________
2.书籍大纲
第一部分——基础：MCP和代理循环
- 为什么选择MCP？
- 问题：为每个代理定制工具集成。 - MCP被誉为“人工智能工具的USB-C”(模型上下文协议? - Model Context ...")) - 服务器与客户端概述；JSON-RPC；工具模式。
- 代理与Claude和Responses循环
- Claude Desktop作为零安装MCP客户端。 (人类) - 使用具有工具调用和结构化输出的OpenAI Responses构建一个最小的自定义代理。 (OpenAI平台) - 日志记录、重试和护栏。
- FastMCP底漆
- 使用FastMCP在大约30行中构建一个“hello world”MCP服务器。 (FastMCP) - 为Claude和您的自定义响应客户端配置它。
______________________________________________________________________
第二部分-电子表格MCP
- 表格数据设计工具
- 形状 product_sales 数据集；如何公开切片/过滤/搜索工具，而不是原始文件读取。 - 工具设计模式：狭义、可组合的工具与大型功能。
- 使用FastMCP实现
- Pandas+FastMCP适用于： get_sales, summarize_sales_by_year等等。 - 验证、错误消息和模式设计。
- 部署到FastMCP云
- 连接仓库，配置机密（例如，私有S3存储桶或数据库）。 - 可观察性：JSON-RPC级别的跟踪工具调用。 (FastMCP)
______________________________________________________________________
第三部分——MCP分析（MATLAB）
- 使用MATLAB MCP核心服务器进行本地原型设计
- 安装和配置MATLAB MCP核心服务器。 (迈斯沃克)
- 将现有的MATLAB分析函数封装为MCP工具。
- 使用Claude/Responses代理调用MATLAB：
- 统计， - 预测， - 情景分析。
- 从桌面到服务器：MPS的MCP框架
- 为什么MATLAB生产服务器适用于多用户、低延迟工作负载。 (迈斯沃克) - 通过MPS框架将MATLAB函数作为MCP工具发布。 - 版本控制工具和处理模型和代码更新。
- 替代方案：将MATLAB编译为Docker/Render
- 对于没有MPS的读者：使用编译器SDK生成运行时映像，并部署到微小MCP垫片后面的Render作为web服务。 (渲染) - 讨论MPS的优缺点（扩展、许可、启动时间）。
______________________________________________________________________
第四部分——MCP和子代理报告
- 设计报告MCP
- 工具API：
- generate_markdown_report(request_id, filters) - export_pptx(markdown_url | data) - export_static_site(markdown_url | data)
- 编排模式：报告MCP应何时调用电子表格/分析MCP，而不是让主代理进行编排。
- 作为子代理进行深入研究
- MCP使用的报告：
- 克劳德或回应作为语境评论的“次要”代理（“深度研究”模式）。
- 提示模式以实现一致的章节/标题输出。
- 格式化输出
- Markdown+封面→ 静态网站（Hugo、MkDocs等）。
- 使用python-pptx/python-docx生成幻灯片/报告，嵌入MATLAB工具生成的图表（保存到S3或Git LFS）。
______________________________________________________________________
第五部分——部署、CI/CD和操作
- GitHub操作管道
- 工作流程：
- 运行测试（Python+MATLAB）， - 运行linting， - 构建文档， - 构建PPTX/Word工件， - 推送Docker镜像/触发FastMCP云部署。
- 计划工作流以重新生成“周报”静态站点。
- 多环境配置
- Dev（本地MCP核心服务器、本地FastMCP服务器）。
- 暂存（FastMCP Cloud+MPS暂存）。
- Prod（FastMCP Cloud+MPS Prod+渲染静态站点或GitHub页面）。
- 监控、安全和成本
- FastMCP云和MPS日志的可观测性。 (完美)
- 秘密管理（API密钥、DB信用）。
- LLM使用的成本控制（费率限制、每份报告的预算）。
- 扩展架构
- 额外的MCP服务器：CRM、票务、CFD结果等。
- 多租户设置；组织级配置模式。
- 如何重用模式 *其他* 书籍/演示。
______________________________________________________________________
3.书中的学习路径
每个部分都以一个“检查点”结束，阅读器在那里有：
- 在第一部分之后：
- 一个正在工作的本地代理循环调用玩具FastMCP服务器。
- 第二部分之后：
- 提供过滤视图的电子表格MCP product_sales.xlsx，可从克劳德和响应代理调用。
- 第三部分之后：
- MATLAB分析工具可通过MCP调用，首先在本地（核心服务器）调用，然后在MPS或Render上调用。
- 第四部分之后：
- 报告MCP，它从自然语言查询中生成端到端的Markdown+PPTX。
- 第五部分之后：
- CI/CD管道、分阶段部署和可公开访问的生成报告静态站点。
______________________________________________________________________
4.技术栈
代理客户
- 基于Claude的MCP客户端 （Claude Desktop）：通过标准MCP配置与您的三台服务器进行通信。 (人类)
- 自定义OpenAI响应客户端：Node/Python客户端，使用Responses API+工具调用来实现相同的“代理循环”，但对计划、重试和日志记录有明确的控制。 (OpenAI平台)
服务器
- 电子表格MCP （快速MCP）
- 建于 FastMCP Python框架（先本地，然后推送到FastMCP Cloud）。 (FastMCP)
- 工具如：
- list_dimensions() - get_sales(year: int, product: str | None, region: str | None) - summarize_by_product(year)
- 支持Pandas阅读 product_sales.xlsx 从数据文件夹中。
- MCP分析
- 本地开发人员： MATLAB MCP核心服务器，公开用于统计、预测、异常检测等的MATLAB函数。 (迈斯沃克) - 生产： MATLAB生产服务器的MCP框架，将MATLAB函数转换为MATLAB生产服务器上可扩展的MCP工具。 (迈斯沃克) - 可选变体：如果读者没有MPS，但有编译器SDK，则将Docker映像中的编译MATLAB组件作为web服务部署在Render上。 (渲染)
- 报告MCP
- Python FastMCP服务器，其工具：
- 呼叫 电子表格MCP + MCP分析.
- 可选择调用“深度研究”子代理（Claude/Responses）进行市场评论。
- 发射：
- generate_markdown_report(...) - generate_powerpoint(...) - generate_word_report(...) - generate_static_site(...)
- 使用python pptx/python docx/静态站点生成器作为实现细节（本书可以选择每种格式一个）。
基础设施
- FastMCP云 用于生产中的电子表格+报表服务器（零配置、CI/CD、可观察性）。 (FastMCP)
- MATLAB生产服务器 （本地或云端）通过MCP框架托管分析工具(迈斯沃克)
- Render.com 用于：
- 托管静态网站（如果不使用GitHub Pages），和/或 - 将编译的MATLAB或辅助服务作为基于Docker的web服务托管。 (渲染)
- GitHub 操作:
- 对每台服务器和代理客户端运行测试。
- 在合并/标记时，构建：
- 来自最新Markdown的静态网站， - PPT/Word工件， - 用于Render/MPS的Docker镜像（如相关）。
______________________________________________________________________
5.回购结构
这是本书的回购结构：
mcp-agents-book/
book/ # Manuscript, notebooks, diagrams
agents/
claude-mcp-client/ # config files + example prompts
responses-agent/ # Python/Node OpenAI Responses client
servers/
spreadsheet-fastmcp/
server.py
product_sales.xlsx
tests/
analysis-matlab-core/
matlab/
analyzeSales.m
forecastDemand.m
mcp-core-config/
tests/
analysis-mps-framework/
matlab/
mps-deploy/ # MPS MCP framework configs
report-fastmcp/
server.py
templates/ # pptx/docx/html templates
tests/
infra/
.github/
workflows/
ci.yml
deploy-fastmcp.yml
build-reports.yml
render/
Dockerfile-matlab-runtime
render.yaml
examples/
01-local-loop/
02-multi-server/
03-deep-research/
04-production-deploy/