MCP Archetypes

🏗️ MCP原型

用于构建模型上下文协议（MCP）客户端和服务器的全面架构模式集合

欢迎来到MCP原型！该存储库展示了用于开发健壮的MCP应用程序的各种架构模式、框架、传输机制和身份验证策略。无论您是在构建天气服务、数据分析工具还是复杂的人工智能应用程序，这些原型都为加速开发提供了久经考验的基础。

联系我们提交想法、评论或新模式。

🚀 里面是什么

MCP原型演示了MCP客户端和服务器的实现，针对MCP规范的不同方面使用不同的框架、传输和授权方法。 服务器实现使用简单、重复的功能，如对weather.gov API的调用，如优秀的 快速入门 由MCP作者指导。

本系列的重点是如何为不同的技术栈、身份验证要求和接口构建MCP服务器和客户端。

📊 架构矩阵

此表概述了此存储库中呈现的服务器和客户端脚本的示例实现。

🔧 体系结构模式

1. 服务器端模式

FastMCP模式

• 用例：具有最少样板的高性能服务器
• 益处：内置运输处理、自动工具注册、资源配置
• 最适合：生产服务、API集成

运输灵活性

• 工作室：非常适合本地开发和直接客户连接
• 超文本传输协议：非常适合基于web的客户端和微服务架构

2. 客户端模式

AWS基岩集成

• 用例：FastMCP与基岩模型的集成
• 组件：不同的API，如Converse API或Bedrock Agent

FastMCP模式

• 用例：高性能客户端，样板最少
• 快速的服务器连接和处理

身份验证策略

• AWS基岩：具有托管身份验证的企业级AI
• 环境变量：安全的凭据管理
• 基于代用券：分布式系统的可扩展身份验证

3. 运输模式

STDIO传输

# Server setup
mcp.run(transport='stdio')

# Client connection
server_params = StdioServerParameters(
    command='python3',
    args=[server_script_path, 'local']
)

HTTP传输

# Server setup
mcp.run(transport='http')

# Client connection (future archetype)
# HTTP client implementation coming soon

🌟 模块详细信息

io_api_server.py：气象数据工具MCP服务器

一个生产就绪的MCP服务器，使用美国国家气象局API提供全面的天气信息。

🎯特征：

• FastMCP框架：闪电般快速的服务器实施
• 实时天气数据：现状和预测
• 警报系统：天气警报和咨询
• 双重运输：支持STDIO和HTTP传输
• 错误处理：针对外部API调用的强大错误管理

🔧提供的工具：

• get_alerts(state) -检索美国任何州的活动天气警报
• get_forecast(latitude, longitude) -获取特定坐标的详细天气预报

运输

• 本地I/O传输

🛡️所需的身份验证和凭据

• 无

io_api_sampling_server.py：通过LLM采样进行翻译的空间新闻服务器

一种高级MCP服务器，使用MCP客户端提供的LLM采样，提供具有智能多语言翻译功能的当前空间新闻。

🎯特征：

• FastMCP框架：采用现代异步架构的高性能服务器实现
• 实时太空新闻：从SpaceflightNews API获取今天的最新太空新闻
• 法学硕士翻译：通过MCP Context使用LLM采样自动翻译为任何语言

🔧提供的工具：

• get_todays_spacenews(language='EN') -使用可选语言翻译检索今天的太空新闻

- 参数: - language （str）：ISO639语言代码（默认：“EN”） - 退货：每篇新闻文章的JSON列表，带有“title”和“summary”键 - 特性：非英语语言的LLM自动翻译

🛠️技术实施：

• 数据源：太空飞行新闻API v4(https://api.spaceflightnewsapi.net/)
• 翻译引擎：使用结构化提示和示例进行上下文采样
• 输出格式：标准化的JSON结构，便于客户端使用

📡API详细信息：

• 端点: /v4/articles/?published_at_gte={date.isoformat()}
• 响应处理：从新闻文章中摘录标题和摘要

运输

• 本地I/O传输（STDIO）

🛡️所需的身份验证和凭据

• 无（SpaceflightNews API公开）
• 翻译功能需要LLM上下文访问

io_resource_server.py：标准MCP资源服务器

一个全面的MCP服务器，使用FastMCP框架演示静态和动态资源配置。

🎯特征：

• FastMCP框架：高性能资源服务器实施
• 静态资源：基于文件的资源，如文档和配置文件
• 动态资源：具有参数化URI的基于模板的资源
• 数据处理：CSV文件处理和JSON转换功能
• 销售数据管理：月度销售数据访问和分析

📊提供的资源：

• README -静态markdown文档资源
• get_sales(year, month) -用于访问月度销售数据的动态资源模板

🔧资源类型：

• 静态资源：README文件作为包含文档元数据的文件资源
• 资源模板：参数化URI模式 resource://sales/{year}/{month} 用于动态销售数据访问

📁示例数据：

• 按月份和年份组织的CSV文件（例如。， january_2024.csv)
• 自动将pandas DataFrame转换为JSON
• 丢失数据文件的错误处理

运输

• 本地I/O传输（STDIO）

🛡️所需的身份验证和凭据

• 无

io_tools_client_bedrock.py：带工具操作的基础基岩AI客户端

一个智能MCP客户端，利用AWS Bedrock强大的语言模型为MCP工具提供自然语言接口。

🎯特征：

• 示例函数 天气预报的自然语言查询
• AWS基岩集成：从AWS和外部提供商（如Anthropic）访问各种模型
• 动态工具调用：自动调用适当的MCP工具

🧠 客户：

• AWS基岩运行时
• Bedrock Converse API（AWS） 文档)
• AWS Converse API工具评估 文档)

运输

• 本地I/O传输

🛡️所需的身份验证和凭据

• Boto3客户端配置

- 区域

• 环境变量

- AWS_bear_TOKEN_BEDROCK

或

- 为运行客户端的服务配置IAM角色

或

- 已配置AWS CLI

或

- AWS_ACCESS_KEY_ID - AWS_SECRET_ACCESS_KEY

io_resources_client_bedrock.py：基岩AI客户端“销售分析”访问MCP资源

一个智能MCP客户端，连接到资源服务器，并利用AWS Bedrock AI模型来分析和解释与销售统计相关的资源数据。

🎯特征：

• 资源发现：自动列出和发现可用资源和资源模板
• AWS基岩集成：利用亚马逊模型进行自然语言处理
• 销售数据分析：用于分析月度销售数据的示例客户端
• 动态资源访问：基于模板的资源检索，通过参数替换减少令牌使用
• AI驱动的洞察：结构化数据的自然语言查询

🧠 人工智能能力：

• 自然语言查询：用简单的英语询问有关销售数据的问题
• 数据上下文集成：将资源文档与数据相结合，以增强分析
• 智能响应：基于销售数据和用户查询的上下文分析

🔧资源操作：

• list_resources() -发现可用的静态资源
• list_resource_templates() -查找动态资源模板
• read_resource(uri) -获取资源内容
• 带参数替换的模板URI解析

📊数据处理：

• CSV数据检索和处理
• 与Bedrock Converse API集成
• 资源环境下的系统快速构建
• 丢失或无效数据的错误处理

运输

• 本地I/O传输（STDIO）

🛡️所需的身份验证和凭据

• Boto3客户端配置

- 地区（美国东部-1）

• 环境变量

- AWS_bear_TOKEN_BEDROCK

或

- 为运行客户端的服务配置IAM角色

或

- 已配置AWS CLI

或

- AWS_ACCESS_KEY_ID - AWS_SECRET_ACCESS_KEY

io_prompt_server.py：带有代码分析的博客生成提示模板

一个专门的MCP服务器，为自动博客文章生成提供复杂的提示模板，具有为技术文档和数据科学受众量身定制的代码分析和内容创建工作流程。

🎯特征：

• FastMCP框架：基于标记的组织的高性能即时服务器实现
• 多阶段博客生成：从代码分析到最终博客文章编译的完整工作流程
• 代码分析：从源代码中智能提取技术关键字
• 内容模板：介绍、主要内容和聚合部分的结构化提示
• 专业音调：针对数据科学和发展受众

🔧提供的提示：

基本交互：

• greet_me(language='EN') -使用ISO 639语言代码生成多语言问候语

代码分析管道：

• get_keywords_from_code(code) -从代码示例中提取5个相关技术关键字

- 输入：源代码字符串 - 输出：JSON格式，带有包含框架和协议名称的关键“关键字” - 聚焦：不包括基本编程语言元素、目标框架和库

内容生成：

• create_intro_from_code(keywords) -生成博客文章介绍部分

- 输入：技术关键字列表 - 输出：面向数据科学受众的5-7句专业介绍

• create_main_section_from_code(keywords, code) -创建详细的主要内容

- 输入：关键字列表和源代码 - 过程：提取5个代码段，提供描述，聚合成主要内容 - 输出：技术博客文章主要部分，包含代码示例和解释

内容组装：

• aggregate_blog_sections(intro, main, outlook) -编译和润色完整的博客文章

- 输入：单独的介绍、主要和展望部分 - 过程：组合部分并打磨语言，以达到专业语气 - 输出：完整、可发布的博客文章

🛠️技术实施：

• 提示结构：基于模板的方法，具有角色定义和明确的任务规范
• 输出格式：针对不同内容类型的结构化JSON和markdown格式
• 内容焦点：专门从事技术和数据科学内容创作
• 标签系统：用“提示”标签组织，便于分类

📝内容工作流：

1. 代码输入 → 通过以下方式提取关键字 get_keywords_from_code()
2. 关键词 → 通过介绍生成 create_intro_from_code()
3. 关键词+代码 → 主要内容通过 create_main_section_from_code()
4. 所有部分 → 最终组装通过 aggregate_blog_sections()

运输

• 本地I/O传输（STDIO）

🛡️所需的身份验证和凭据

• 无

🎯使用案例：

• 自动生成技术文档
• 从代码库创建博客文章
• 开发人员内容工作流
• 数据科学项目文档

io_prompt_client_bedrock.py：用于自动博客生成的Bedrock AI客户端

一个智能MCP客户端，利用AWS Bedrock AI模型，使用提示服务器的结构化工作流从源代码编排自动博客文章生成。

🎯特征：

• FastMCP客户端集成：使用FastMCP框架无缝连接到MCP提示服务器
• AWS基岩AI：利用DeepSeek R1模型生成高质量内容
• 自动化博客工作流程：从源代码输入完成端到端的博客创建
• 多级加工：协调关键字提取、介绍/主要内容生成和最终组装
• 专业内容：为技术受众制作可发布的博客文章

🧠 AI驱动的管道：

1.代码分析阶段：

• run_keyword_prompt(code) -从源代码中提取技术关键字
• 过程：向提示服务器发送代码，处理JSON响应并进行错误处理
• 输出：相关技术关键词的干净列表

2.内容生成阶段：

• run_intro_prompt(keywords) -从关键字创建引人入胜的介绍
• run_main_prompt(keywords, code) -通过代码分析生成详细的主要内容
• 过程：通过Bedrock Converse API使用结构化提示
• 聚焦：面向数据科学和发展受众的技术写作

3.组装阶段：

• run_aggregate_prompt(intro, main, outlook) -编译并完善最终博客文章
• 过程：整合所有部分，运用专业音色
• 输出：完整、可发布的博客文章

🔧客户操作：

• 快速发现: list_prompts() -从连接的服务器中发现可用提示
• 健康检查: ping() -验证服务器连接和响应能力
• 文件处理：接受代码文件路径并自动处理文件读取
• 错误处理：强大的JSON解析，带有回退错误消息

🛠️技术实施：

• 模型：通过AWS Bedrock的DeepSeek R1（美国DeepSeek.R1-v1:0）
• 运输：与MCP提示服务器的STDIO连接
• 配置：AWS区域特定设置（us-east-1）
• 环境：支持.env文件进行凭据管理

📝完整工作流示例：

python io_prompt_client_bedrock.py server_script.py source_code.py

工艺流程：

1. 输入：源代码文件→ 分析：提取关键字
2. 生成：使用AI创建介绍和主要部分
3. 汇编：结合前景和抛光出版
4. 输出：完整的博客文章已准备好发表

🎯专业功能：

• JSON响应解析：处理代码块删除和JSON清理
• 硬编码关键字：使用\[‘MCP’、‘FastMCP’、“Prompts”\]进行一致的品牌推广
• Outlook集成：包括指向www.evo-byte.com的促销内容
• 多模型支持：可针对不同基岩模型进行配置

运输

• 本地I/O传输（STDIO）

🛡️所需的身份验证和凭据

• AWS基岩通道:

- Boto3客户端配置（区域：us-east-1） - DeepSeek R1模型访问权限

• 环境变量:

- AWS_BEARER_TOKEN_BEDROCK（或配置的IAM角色/CLI/访问密钥）

• 依赖项:

- python-dotenv 环境管理 - fastmcp 用于MCP客户端功能

🎯使用案例：

• 从代码库中自动生成开发人员文档
• 为营销团队生成技术博客
• 开发人员关系内容创建
• 代码库文档自动化
• 从实例中生成教育内容

oauth_github_api_server.py：带有GitHub OAuth身份验证的Weather API服务器

一个生产就绪的MCP服务器，使用GitHub OAuth演示安全身份验证模式，提供具有用户特定访问控制的天气信息。

🎯特征：

• FastMCP框架：内置身份验证的高性能HTTP服务器实现
• GitHub OAuth集成：通过GitHub OAuth应用程序工作流进行安全用户身份验证
• 受保护的工具：只有经过身份验证的用户才能访问天气工具
• 用户上下文：访问经过身份验证的用户的GitHub个人资料信息
• HTTP传输：适用于浏览器客户端和Web应用程序的基于Web的服务器
• 调试模式：用于开发和故障排除的全面日志记录

🔧提供的工具：

• get_user_info() -返回经过身份验证的GitHub用户信息

- 退货：GitHub用户名、显示名称和配置文件数据 - 认证：需要有效的GitHub OAuth令牌

• get_alerts(state) -检索美国任何州的活动天气警报

- 参数: state （str）-两个字母的美国州代码 - 认证：受保护-需要GitHub身份验证

• get_forecast(latitude, longitude) -获取特定坐标的详细天气预报

- 参数: latitude （浮动）， longitude （浮动） - 认证：受保护-需要GitHub身份验证

🛠️技术实施：

• 验证提供者：具有OAuth 2.0流的FastMCP GitHubProvider
• 数据源：美国国家气象局API，带有正确的User-Agent标头
• 运输：支持CORS和OAuth回调处理的HTTP服务器
• 安全：令牌验证和用户会话管理
• 错误处理：针对auth和API调用的全面错误管理

🔐OAuth配置：

• GitHub OAuth应用程序设置：需要注册的GitHub OAuth应用程序
• 回调URL: http://localhost:8000/auth/callback （可配置）
• 范围：用于身份验证的用户配置文件访问
• 令牌存储：具有过期管理的安全令牌处理

📡API详细信息：

• 基本URL: http://localhost:8000 （可配置）
• MCP端点: /mcp -主MCP协议端点
• 身份验证端点: /auth/callback -GitHub OAuth回调处理程序
• 天气API：国家气象局与限速系统的整合

运输

• HTTP传输（端口8000）
• OAuth回调处理
• Web浏览器兼容性

🛡️所需的身份验证和凭据

• GitHub OAuth应用程序:

- GITHUB_OAUTH_CLIENT_ID -您的GitHub OAuth应用程序客户端ID - GITHUB_OAUTH_CLIENT_SECRET -您的GitHub OAuth应用程序客户端密码

• 环境配置:

- OAuth应用程序必须配置正确的回调URL - 基本URL必须与OAuth应用程序设置匹配

🎯使用案例：

• 多租户应用程序
• 用户特定的数据访问
• 需要用户身份验证的企业应用程序
• 认证MCP模式的开发

oauth_github_tools_client_bedrock.py：具有GitHub OAuth身份验证的Bedrock AI客户端

一个智能MCP客户端，将AWS Bedrock AI功能与GitHub OAuth身份验证相结合，通过自然语言界面提供对天气工具的安全访问。

🎯特征：

• FastMCP客户端集成：基于HTTP的连接到受OAuth保护的MCP服务器
• GitHub OAuth流程：使用GitHub进行基于浏览器的自动身份验证
• AWS基岩AI：使用Amazon Nova Lite模型进行高级自然语言处理
• 经过身份验证的工具访问：安全访问受保护的气象工具
• 交互式聊天界面：使用人工智能处理的自然语言天气查询
• 用户上下文：访问经过身份验证的用户的GitHub个人资料信息

🧠 人工智能驱动的工作流程：

1.身份验证阶段：

• OAuth初始化：自动启动GitHub OAuth流
• 浏览器身份验证：在默认浏览器中打开GitHub登录
• 许可证管理：安全的令牌存储和验证
• 用户档案：检索并显示经过身份验证的用户信息

2.工具发现阶段：

3.查询处理阶段：

🔧客户操作：

🛠️技术实施：

• AI模型：通过AWS Bedrock下载亚马逊Nova Lite（Amazon.Nova-Lite-v1:0）
• 认证：与GitHub集成的FastMCP OAuth提供程序
• 运输：具有OAuth令牌身份验证的HTTP

📝完整工作流示例：

python oauth_github_tools_client_bedrock.py

🔐身份验证流程：

• 首次运行：自动打开GitHub OAuth同意屏幕
• 令牌存储：安全地存储OAuth令牌以供后续运行
• 令牌刷新：自动处理令牌过期和刷新
• 用户验证：在访问工具之前验证用户身份

运输

• 使用OAuth身份验证的HTTP传输

🛡️所需的身份验证和凭据

• GitHub OAuth应用程序:

- 必须与服务器的OAuth配置匹配 - 用户必须授权OAuth应用程序

• AWS基岩通道:

- Boto3客户端配置（区域：us-east-1） - Amazon Nova Lite模型访问权限

• 环境变量:

- AWS凭据（IAM角色、CLI或环境变量） - 可选： .env 凭证管理的文件支持

🎯使用案例：

• 保护多用户应用程序
• 具有用户身份验证的企业AI助手
• 开发经过身份验证的会话界面

🤝 贡献

我们欢迎捐款！以下是如何帮助扩展MCP原型：

1. 新原型：添加不同框架的实现
2. 运输模式：WebSockets、gRPC、消息队列
3. 身份验证方法：OAuth、JWT、API密钥
4. 文档：示例、教程、最佳实践

添加新原型

1. 选择您的框架/运输组合
2. 按照现有模式实施
3. 添加全面的文档
4. 更新架构矩阵
5. 提交拉取请求

📚 资源

• 模型上下文协议规范
• FastMCP文档
• AWS基岩开发人员指南
• 美国国家气象局API
• 太空飞行新闻API

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

______________________________________________________________________

🎯 准备好构建下一个MCP应用程序了吗？ 从这些原型开始，并根据您的特定需求进行定制。这里展示的模式可以从简单的原型扩展到生产就绪的系统。