Chuk MCP Playbook

Chuk MCP剧本服务器

一个可查询的剧本存储库MCP服务器，将可执行知识存储为markdown，并通过快速关键字搜索进行检索。

概述

此MCP服务器充当“剧本库”，它：

• 摄入 markdown剧本，包含简明英语的分步说明
• 商店 它们存储在内存中（通过工厂模式具有可扩展存储）
• 退货 LLM友好的剧本，可以直接提供给AI规划者
• 查询 利用自然语言实现快速检索

建筑

遵循干净的建筑原则：

src/chuk_mcp_playbook/
├── models/              # Pydantic domain models
│   └── playbook.py      # Playbook, PlaybookMetadata, PlaybookQuery
├── storage/             # Storage layer with factory pattern
│   ├── base.py          # Abstract PlaybookStorage interface
│   ├── factory.py       # StorageFactory and StorageType enum
│   └── providers/       # Storage implementations
│       └── memory.py    # In-memory storage (default)
├── services/            # Business logic
│   └── playbook_service.py  # PlaybookService
├── loader.py            # Markdown playbook loader
└── server.py            # MCP server with async tools

关键设计原则

• Pydantic土著：所有型号都使用Pydantic进行类型安全
• 异步本机：所有操作都是异步的
• 没有魔术弦：贯穿始终的类型安全枚举和Pydantic模型
• 工厂模式：易于添加新的存储提供程序（矢量数据库、SQL等）
• 清洁分离：模型、存储、服务和服务器已正确分离

安装

# Clone or navigate to the repository
cd chuk-mcp-playbook

# Install dependencies
pip install -e .

# Or install from parent directory
pip install -e /Users/christopherhay/chris-source/chuk-ai/mcp-servers/chuk-mcp-server
pip install -e .

用法

运行服务器

服务器支持两种传输模式：

STDIO模式（默认-适用于Claude Desktop，mcp-cli）

# Using uv (recommended)
uv run chuk-mcp-playbook

# Or with explicit transport
uv run chuk-mcp-playbook --transport stdio

# Or activate venv first
source .venv/bin/activate
chuk-mcp-playbook

HTTP模式（用于web/API访问）

# Using uv
uv run chuk-mcp-playbook http

# Or using make
make run-http

服务器将自动从 playbooks/ 启动时的目录。

快速测试

运行附带的测试脚本以验证一切正常：

python test_server.py

MCP工具

query_playbook

使用自然语言查询剧本。

question: str  # e.g., "How do I get sunset times?"
top_k: int = 3  # Max results to return
→ Returns: Markdown content of the most relevant playbook

ingest_playbook

将新的剧本添加到存储库中。

title: str
content: str  # Markdown content
description: str
tags: list[str] | None = None
author: str | None = None
→ Returns: Success message

list_playbooks

列出所有可用的剧本。

→ Returns: list[str]  # All playbook titles

get_playbook

按确切的标题检索特定的剧本。

title: str
→ Returns: Markdown content or error message

get_stats

获取存储库统计信息。

→ Returns: {"total_playbooks": int}

示例

请参阅 examples/ 实际演示目录：

• 01_basic_query.py -基本查询和检索
• 02_ingest_playbook.py -以编程方式创建和添加剧本
• 03_async_api_usage.py -并行操作和性能
• 04_自定义存储.py -构建自定义存储提供商
• 05_mcp_client_simulation.py -AI规划师集成工作流程

运行所有示例：

source .venv/bin/activate
cd examples
./run_all.sh

剧本格式

剧本是具有特定结构的标记文件，专为LLM消费而设计：

# Playbook: [Title]

## Description
Brief description of what this playbook does

## Prerequisites
- Required inputs or conditions

## Steps

1. First step in plain English
2. Second step with clear instructions
3. Continue with all necessary steps

## MCP Tools Required

### server-name
- **Tool**: `tool_name`
- **Parameters**:
  - `param1` (type): Description
  - `param2` (type): Description

## Example Usage

**Input**: Example user question

**Process**:
1. Step breakdown
2. ...

**Output**:

预期结果

## Expected Response Format

Format for the final output

## Error Handling

- Common errors and how to handle them

## Notes

- Additional helpful information

示例播放手册

天气播放手册

使用 chuk-mcp-open-meteo 服务器：

1. 获取当前天气状况：任何位置的实时天气数据
2. 获取天气预报：包含详细指标的多日天气预报
3. 比较历史天气：比较不同时间段的天气状况
4. 比较重复日期天气：分析重复日期（生日、假期）的天气模式
5. 计划多日旅行天气：为多天旅行制定天气计划

时间播放簿

使用 chuk-mcp-time 服务器：

基本工具播放手册：

1. 获取当前UTC时间：使用NTP共识的高精度UTC时间
2. 获取时区时间：任何具有夏令时信息的IANA时区的当前时间
3. 检查系统时钟漂移：检测和诊断时钟同步问题
4. 跨时区转换时间：同时跨多个时区显示当前时间
5. 在时区之间转换时间：转换任意两个时区之间的特定日期时间
6. 列出可用时区：搜索并发现有效的IANA时区标识符
7. 获取时区夏令时信息：查看任何时区的夏令时时间表和即将到来的过渡

简单问题场景： 8\. \[城市\]现在几点？：回答“伦敦/东京等地现在几点？” 9\. 时钟什么时候变？：回答“夏令时在\[地点\]何时开始/结束？” 10\. 位置在夏令时吗？：回答“悉尼/纽约等地实行夏令时吗？” 11\. 城市是什么时区？：回答“凤凰城/孟买等地的时区是什么？”

复杂场景： 12\. 安排全球会议：跨多个时区查找最佳会议时间 13\. 解决时间同步问题：诊断并修复时间同步问题 14\. 围绕夏令时过渡制定计划：处理调度和部署中的DST更改

与AI Planner集成

这些剧本旨在与 chuk-ai-planner:

1. 法学硕士问：“我怎么知道日落时间？”
2. 计划员来电： query_playbook(question="sunset times")
3. 服务器返回：包含英文步骤的完整剧本
4. Planner解析剧本并创建子计划
5. Planner使用指定的MCP工具执行步骤

扩展存储

要添加新的存储提供程序，请执行以下操作：

1. 在中创建新提供程序 storage/providers/:

from chuk_mcp_playbook.storage.base import PlaybookStorage

class MyStorage(PlaybookStorage):
    async def add_playbook(self, playbook: Playbook) -> None:
        # Implementation
        pass

    # Implement all abstract methods...

1. 添加到工厂 storage/factory.py:

class StorageType(str, Enum):
    MEMORY = "memory"
    MY_STORAGE = "my_storage"  # Add new type

class StorageFactory:
    @staticmethod
    def create(storage_type: StorageType, **kwargs):
        if storage_type == StorageType.MY_STORAGE:
            return MyStorage(**kwargs)
        # ...

未来的增强功能

• 向量存储：添加ChromaDB/LanceDB提供程序进行语义搜索
• 永久存储：SQLite/PPostgreSQL提供者
• 剧本版本控制：跟踪随时间的变化
• 模板：常见模式的剧本模板
• 验证：剧本结构的模式验证
• REST API：用于web集成的HTTP端点

演出

• 内存搜索：亚毫秒查询时间
• 初创公司：在\<100ms内加载所有剧本
• 异步：全程无阻塞运行
• 可扩展的：工厂模式已准备好用于高性能后端

许可证

麻省理工学院