SAAGA MCP服务器Cookie切割器

A. 厨师切菜机用于创建具有SAAGA装饰器、平台感知配置和可选Streamlit管理UI的MCP（模型上下文协议）服务器的模板。

🚀 最快入门方法：Claude代码命令

学习MCP和构建服务器的最快方法是使用Claude Code的交互式命令。

Claude Code快速入门

生成您的项目：

   cookiecutter https://github.com/SAGAAIDEV/saaga-mcp-server-cookie-cutter.git
   cd your-project-name

在项目中启动Claude Code：

   claude

使用以下命令从零切换到工作的MCP服务器：

- /getting-started -根据您的经验水平调整的交互式教程 - /add-tool -在指导下创建您的第一个MCP工具 - /generate-tests -自动生成全面的测试 - /remove-examples -准备生产时清理示例代码

就是这样！ 这些命令将教你MCP，帮助你构建工具，并让你在几分钟内运行。

替代方案：AI助手设置

如果您使用的是其他AI助手（不是Claude Code），可以使用我们的设置提示：

*“我想使用SAAGA模板创建一个新的MCP服务器。请阅读并执行中的安装说明 SETUP_ASSISTANT_PROMPT.md"*

特性

FastMCP集成：基于现代FastMCP框架构建，支持三重传输（STDIO/SSE/Streamable HTTP）
SAAGA装饰：自动应用异常处理、日志记录和并行化装饰器
OAuth令牌传递：可选的OAuth支持，客户端通过上下文传递令牌（服务器中没有OAuth流）
平台感知配置：使用跨平台配置管理 platformdirs
可选流线型UI：用于配置和日志查看的管理界面
SQLite日志记录：具有数据库持久性的综合日志记录系统
开发者友好：预提交挂钩、GitHub操作和全面的文档

快速开始

先决条件

Python 3.11或更高版本
紫外线的 -一个速度极快的Python包管理器
厨师切菜机

安装

# Install UV (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh  # On macOS/Linux
# Or visit https://github.com/astral-sh/uv for Windows instructions

# Install cookiecutter as a UV tool
uv tool install cookiecutter

用法

生成新的MCP服务器项目：

# Using UV tool
uv tool run cookiecutter https://github.com/SAGAAIDEV/saaga-mcp-server-cookie-cutter.git

# Or if you installed cookiecutter globally
cookiecutter https://github.com/SAGAAIDEV/saaga-mcp-server-cookie-cutter.git

或者从当地收银台：

# Using UV tool
uv tool run cookiecutter /path/to/saaga-mcp-server-cookie-cutter

# Or if you installed cookiecutter globally
cookiecutter /path/to/saaga-mcp-server-cookie-cutter

配置选项

系统将提示您输入以下配置选项：

project_name：人类可读的项目名称
project_slug：Python包名称（自动生成）
description：项目描述
author_name：你的名字
author_email：您的电子邮件地址
python_version：目标Python版本（3.11或3.12）
server_port：HTTP传输的默认服务器端口
include_oauth_passthrough：包括OAuth令牌传递支持（是/否）
include_oauth_backend：包括OAuth后端支持（是/否）
oauth_backend_port：OAuth后端服务的端口（默认值：8080）

服务器参考实现示例

这 example_server/ 目录包含一个功能齐全的MCP服务器，演示了此模板的所有功能：

✅ 使用具有适当参数自检的SAAGA装饰器
✅ 三重传输支持（STDIO、SSE和流式HTTP）
✅ 显示同步和异步模式的示例工具
✅ 完整的配置管理
✅ 正确的日志记录设置

测试示例服务器

cd example_server
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
# Or simply use: uv shell

uv sync

# Test with MCP Inspector
uv run mcp dev example_server/server/app.py

# Or run directly
uv run python -m example_server.server.app

# Run the Streamlit Admin UI
uv run streamlit run example_server/ui/app.py

有关MCP检查器中每个工具的详细测试说明和示例，请参阅 MCP_INSPECTOR_TEST_GUIDE.md.

在构建自己的MCP工具时，使用示例服务器作为参考，以了解：

装饰器如何保存函数签名
正确的刀具注册模式
配置管理最佳实践
日志记录和错误处理方法

有关装饰器模式的详细信息，请参见解码器_处理器.md此文档也包含在每个生成的项目中。

生成的项目结构

your-project/
├── your_project/
│   ├── __init__.py
│   ├── config.py              # Platform-aware configuration
│   ├── server/
│   │   └── app.py             # FastMCP server with auto-decorators
│   ├── tools/                 # Your MCP tools
│   │   └── example_tools.py   # Example tools (optional)
│   ├── decorators/            # SAAGA decorators
│   │   ├── exceptions.py      # Exception handling
│   │   ├── logging.py         # SQLite logging
│   │   ├── parallelize.py     # Parallelization support
│   │   └── oauth_passthrough.py # OAuth token passthrough (optional)
│   └── ui/                    # Streamlit admin UI (optional)
│       ├── app.py            # Main UI entry point with navigation
│       ├── pages/            # Multi-page structure
│       │   ├── 1_Home.py    # Dashboard with server status
│       │   ├── 2_Configuration.py # Config management
│       │   └── 3_Logs.py    # Log viewer and analysis
│       └── lib/              # Shared UI components
│           ├── components.py # Reusable UI elements
│           ├── styles.py     # CSS and theming
│           └── utils.py      # Helper functions
├── tests/                     # Test suite
├── docs/                      # Documentation
│   └── DECORATOR_PATTERNS.md # Detailed decorator guidance
├── BUILD.bazel               # Bazel build configuration
├── .claude/                  # AI Assistant Integration
│   └── commands/             # Custom commands for development workflow
│       ├── getting-started.md # Interactive onboarding
│       ├── add-tool.md       # Tool creation wizard
│       ├── generate-tests.md # Test generation
│       └── remove-examples.md # Cleanup example code
├── .reference/               # Reference patterns and documentation
│   ├── patterns/            # Code patterns
│   └── mcp-*.md            # MCP documentation
├── pyproject.toml            # Project configuration
├── README.md                 # Project documentation
├── .gitignore               # Git ignore rules
└── LICENSE                  # MIT license

主要特点

Bazel集成

生成的项目包括 BUILD.bazel 与SAAGA构建系统无缝集成的文件。这使得：

在SAAGA基础设施中自动注册
通过Bazel进行一致的依赖关系管理
易于与其他SAAGA组件集成

SAAGA装饰

该模板会自动将三个关键装饰器应用于您的MCP工具：

异常处理程序：优雅的日志错误处理
工具记录器：SQLite数据库的全面日志记录
使平行：计算密集型工具的可选并行处理

平台感知配置

配置文件会自动放置在适当的位置：

macOS： ~/Library/Application Support/your-project/
Linux： ~/.local/share/your-project/
窗户： %APPDATA%/your-project/

流线型管理界面

该模板包括一个全面的基于网络的管理界面：

仪表盘

Streamlit Admin UI Dashboard

仪表板提供实时服务器状态监控、项目信息和对常见操作的快速访问。

配置编辑器

Streamlit Admin UI Configuration

配置页面允许您编辑服务器设置，具有以下功能：

实时验证
显示更改的差异预览
导出/导入功能（JSON和YAML）
确认后重置为默认值

日志查看器

Streamlit Admin UI Logs

日志页面提供全面的日志分析，包括：

日期范围过滤
状态筛选（成功/错误）
工具特定过滤
导出功能

特性

🏠 仪表盘：服务器状态监视、项目信息和快速操作
⚙️ 配置：具有验证和差异预览的服务器配置管理
📊 日志：具有高级过滤和导出功能的日志查看器
🎨 现代用户界面：具有自定义CSS和响应式设计的专业界面
🔄 实时状态：通过端口检查进行实时服务器监控
🛡️ 错误处理：优雅的降级和回退模式

运行管理UI

生成项目后：

# Install your project
cd your-project
uv venv
uv sync

# Start the admin UI
uv run streamlit run your_project/ui/app.py

# In another terminal, start your MCP server (for status monitoring)
uv run python -m your_project --transport sse --port 3001

管理UI将在 http://localhost:8501 并且可以监视在端口3001上运行的MCP服务器。

uI结构

ui/
├── app.py              # Main Streamlit entry point with navigation
├── pages/              # Multi-page structure
│   ├── 1_🏠_Home.py   # Dashboard with server status
│   ├── 2_⚙️_Configuration.py  # Config management
│   └── 3_📊_Logs.py   # Log viewer with filtering
└── lib/               # Shared utilities
    ├── components.py  # Reusable UI components
    ├── styles.py      # CSS styling and themes
    └── utils.py       # Helper functions and server status checks

独立经营

管理UI独立于MCP服务器工作：

✅ 服务器正在运行：显示实时状态和监控
✅ 服务器已停止：具有回退数据和占位符的函数
✅ 单独模式：所有UI功能都可以在不依赖服务器的情况下工作

发展

人工智能辅助开发工作流程

生成的项目包括AI助手（Claude、Cursor等）的自定义命令 .claude/commands/:

入门指南 (/getting-started)：适应您经验水平的交互式入职培训
添加工具 (/add-tool)：引导工具创建，包括研究、规划和实施
生成测试 (/generate-tests)：根据MCP模式自动生成测试
删除示例 (/remove-examples)：创建自己的工具后清理示例代码

这些命令为MCP工具开发提供了结构化、可重复的工作流程。

为发展而设立

克隆此存储库
创建虚拟环境并安装依赖关系：

   uv venv
   uv sync --extra dev

安装预提交挂钩： uv run pre-commit install

OAuth令牌传递功能

当您使用生成项目时 include_oauth_passthrough=yes，你会得到：

OAuth直通装饰器：检查客户端传递的OAuth令牌的上下文
GitHub示例工具：演示OAuth使用的三个工作工具
测试脚本：使用真实GitHub令牌进行测试的即用型脚本
零服务器配置：MCP服务器不需要OAuth设置

如何测试OAuth工具

获取GitHub代币:

- 首选https://github.com/settings/tokens - 使用生成令牌 repo 和 user 范围

使用提供的脚本进行测试:

   cd your-generated-project
   python test_oauth_private_repo.py gho_YOUR_TOKEN owner/repo

重要：MCP服务器不处理OAuth流。客户必须：

- 获取OAuth令牌（通过他们自己的OAuth流） - 通过 _meta MCP请求中的参数

查看生成的 docs/OAUTH_PASSTHROUGH.md 以获取完整的文档。

测试

运行测试套件：

pytest tests/

测试模板生成：

cookiecutter . --no-input

启用OAuth的测试：

cookiecutter . --no-input include_oauth_passthrough=yes

贡献

请阅读贡献.md 有关我们的行为准则和提交pull请求流程的详细信息。

面向模板开发人员

如果您正在改进或维护此炊具模板，请注意：

🚨 关键架构决策

SAAGA装饰是核心：装饰器模式是此模板的基础。装饰器行为的更改将影响所有生成的项目。

仅异步模式：所有装饰器都需要异步函数。这是必须保持的SAAGA标准。

签名转换：The parallelize 装饰器有意转换函数签名。这允许批量处理，但需要小心处理。

注册模式：工具通过列表注册(example_tools, parallel_example_tools)而不是装饰师。这允许正确的装饰器链接。

📚 技术文档

有关装饰器实现的详细技术信息：

看 docs/DECORATOR_PATTERNS.md 了解实施细节
审查 example_server/ 用于工作参考实现
检查生成的项目文档，以了解最终用户体验

⚠️ 更改之前

了解当前模式：装饰链顺序很重要
使用MCP检查员进行测试：确保参数自检仍然有效
验证签名转换：并行工具必须显示 kwargs_list: List[Dict]
更新所有文档：模板和生成的项目文档

建筑

MCP服务器生命周期

MCP服务器由MCP客户端（Claude Desktop、Cursor等）通过配置启动。生成的服务器：

从平台特定位置加载配置
自动应用SAAGA装饰器
在FastMCP框架中注册工具
通过stdio或SSE传输处理客户端连接

装饰应用模式

在服务器初始化期间，该模板会自动将SAAGA装饰器应用于所有工具。以下是实际使用的模式：

# From server/app.py - How decorators are applied
for tool_func in example_tools:
    # Apply SAAGA decorator chain: exception_handler → tool_logger
    decorated_func = exception_handler(tool_logger(tool_func, config.__dict__))
    mcp_server.tool(name=tool_func.__name__)(decorated_func)

for tool_func in parallel_example_tools:
    # Apply SAAGA decorator chain: exception_handler → tool_logger → parallelize
    decorated_func = exception_handler(tool_logger(parallelize(tool_func), config.__dict__))
    mcp_server.tool(name=tool_func.__name__)(decorated_func)

⚠️ 重要：所有SAAGA装饰器都需要异步函数。并行装饰器还转换函数签名。

例子

基本MCP工具

工具被定义为异步函数，并在添加到 example_tools 列表：

# In your_project/tools/my_tools.py
async def example_tool(message: str) -> str:
    """Example MCP tool with automatic decorators."""
    return f"Processed: {message}"

# Add to example_tools list to register
example_tools = [example_tool]

并行处理工具

并行工具必须是异步的，并将其签名转换为接受 List[Dict]:

# Original function definition
async def process_item(item: str, operation: str = "upper") -> str:
    """Process a single item - will be parallelized."""
    if operation == "upper":
        return item.upper()
    elif operation == "lower":
        return item.lower()

# Add to parallel_example_tools list
parallel_example_tools = [process_item]

# After decoration, MCP clients call it with:
# [{"item": "hello", "operation": "upper"}, {"item": "world", "operation": "lower"}]

许可证

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

致谢

FastMCP 优秀的MCP框架
厨师切菜机对于模板系统

Saaga MCP Server Cookie Cutter

快速接入

详细介绍