MCP Playbook Server

MCP Playbook 服务

一个 Model Context Protocol（MCP）服务，用于管理项目文档，并将对话日志保存到用户指定的目标项目目录中。

与 Claude Desktop 或 MCP 客户端搭配使用

要在 Claude Desktop 中使用此 MCP 服务，需要在 Claude Desktop 设置中添加配置项。具体的 command 和 args 取决于你选择的服务运行方式（例如，直接通过 node 运行或使用 Docker）。

首先，确保将此提示词添加到你的 cursor rules、cline rules 或 windsurf rules 中：

ALWAYS run the `init_playbook` tool before starting to get instructions on how things should be done and documented.

然后，将以下配置添加到你的 MCP 客户端：

{
  "mcpServers": {
    "mcp-playbook": {
      "command": "npx",
      "args": ["-y", "@dwarvesf/mcp-playbook@latest"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_github_token_here"
      }
    }
  }
}

如需配置 MCP 服务的详细说明，请参阅 Claude Desktop 文档。

MCP 的幕后工作原理

MCP Playbook 服务通过接收 MCP 客户端（例如 Claude Desktop）发送的工具调用请求来运行。这些请求由 src/index.ts 文件处理，该文件是服务的入口点。

graph LR
    A[MCP Client] --> B["CallToolRequestSchema"];
    A --> E["ListToolsRequestSchema"];
    A --> F["ListPromptsRequestSchema"];
    A --> G["GetPromptRequestSchema"];

    subgraph src/index.ts
        B
        E
        F
        G
    end

    B --> C["Switch Case (toolName)"];

    subgraph src/tools/
        C --> C1("init_playbook");
        C --> C2("create_adr");
        C --> C3("search_runbook");
        C --> C4("... ... ...");
    end

    C1 --> D1("handleInitPlaybook");
    C2 --> D2("handleCreateAdr");
    C3 --> D3("handleSearchRunbook");
    C4 --> D4("... ... ...");

    E --> D12("toolDefinitions");
    F --> D13("handleListPrompts");
    G --> D14("handleGetPrompt");

    subgraph src/handlers/
        D1
        D2
        D3
        D4
        D12
        D13
        D14
    end

1. 工具调用请求： MCP 客户端向服务发送 CallToolRequest，并指定 toolName 和任何必要的 arguments。
2. 请求处理： src/index.ts 文件使用 server.setRequestHandler(CallToolRequestSchema, async (request: CallToolRequest) => { ... }) 为 CallToolRequest 设置请求处理器。
3. 工具路由（Switch Case）： 请求处理器内部的 switch 语句根据 toolName 将请求路由到相应的处理函数。
4. 处理器执行： switch 语句中的每个 case 都会调用位于 src/handlers.ts 文件中的专用处理函数（例如，handleCreateSpec、handleSearchRunbook、handleSyncPrompt）。这些处理器包含每个工具的具体逻辑。
5. 结果： 处理函数执行所请求的操作并返回结果，然后将结果发送回 MCP 客户端。

此流程可确保每次工具调用都路由到正确的执行逻辑，使服务能够执行各种文档和实用任务。

可用工具

工具名称	描述
init_playbook	向大模型提供有关 mcp-playbook 服务用途的说明，该服务旨在促进本地项目文档管理，并支持为 AI 驱动的 playbook 部分复制文档和聊天记录。
create_spec	在目标项目的 docs/specs/ 目录中创建或覆盖新的规格说明文件（例如 PRD、RFC、架构规划）。规格说明文件将按照 spec-name.md 的命名约定命名，并带有序号。
create_adr	在目标项目的 docs/adr/ 目录中创建或覆盖新的架构决策记录（ADR）文件。ADR 文件将按照 adr-name.md 的命名约定命名，并带有序号。
create_changelog	在目标项目的 docs/changelog/ 目录中创建新的、详细且面向用户的变更日志条目文件。每个变更日志条目都是单独的文件，按照 changelog-entry.md 的命名约定命名，并带有序号。
distill_project_runbook	在目标项目中创建或更新中央文件 docs/runbook.md。大模型负责分析现有项目文档（ADR、规格说明等）和当前的 docs/runbook.md（如果存在），然后综合这些信息，编写一份全面的运行手册。该工具会保存大模型生成的内容，并覆盖之前的 docs/runbook.md。
save_and_upload_chat_log	捕获当前对话历史，将其保存为目标项目 .chat/ 目录中的 Markdown 文件，并上传到 dwarvesf/prompt-log GitHub 仓库。需要提供用户 ID 以便整理。
search_runbook	在 dwarvesf/runbook GitHub 仓库中模糊搜索关键词。如果关键词包含空格，则搜索完整短语或单个词。返回匹配度最高的 5 项及其完整内容和总数。
search_prompts	在 dwarvesf/prompt-db GitHub 仓库中模糊搜索关键词（不包括 .synced_prompts/ 文件夹）。
suggest_runbook	在 dwarvesf/runbook 仓库中创建或更新 Pull Request，以添加新的运行手册条目。
sync_prompt	将大模型提示词同步到 dwarvesf/prompt-db GitHub 仓库。
think	使用该工具思考某个问题。它不会获取新信息或对仓库进行任何更改，只会记录思考过程。在需要复杂推理或头脑风暴时使用。

概述

此 mcp-playbook 服务是一个独立的 Node.js/TypeScript 应用程序，通过模型上下文协议（MCP）提供一组可访问的工具。其主要功能是帮助大模型在指定的项目目录中整理文档，以及保存／上传对话历史记录。与可能依赖外部 commander 或 github 环境的工具不同，此服务直接使用 Node.js 内置模块（fs、path、https）和 node-fetch 等库实现文件系统操作及 GitHub API 交互。

此服务对大模型指定的 target_project_dir 进行操作，并管理该位置下的文件和目录。它_不会_在自身的仓库结构中存储文档或聊天记录。

数据流与交互

AI 对话、文件探索、大模型、mcp-playbook 服务与 GitHub 仓库之间的交互可视化如下：

graph TD
    A[LLM] --> B("AI Conversation")
    B --> C{Explore Files}
    C -->|Files with Prompts| D("Prompts in Files")
    C -->|Files without Prompts| B
    B -->|Provides Context| F("MCP Playbook Server")
    D -->|Provides Context| F
    F -->|suggest_runbook| G["dwarvesf/runbook (Practices/Specs)"]
    F -->|save_and_upload_chat_log| H["dwarvesf/prompt-log (Conversation Logs)"]
    F -->|sync_prompt| I["dwarvesf/prompt-db (Synced Prompts)"]

此图展示了 AI 对话以及文件探索过程中发现的提示词如何为 MCP Playbook 服务提供上下文。随后，服务会执行 suggest_runbook、save_and_upload_chat_log 和 sync_prompt 工具，与相应的 GitHub 仓库进行交互。

工具详情

init_playbook

向大模型说明 mcp-playbook 服务的用途：帮助整理本地项目文档，并为 AI 驱动的 playbook 实现文档和聊天记录的部分复制。

参数： 无。

返回： 包含该说明的 JSON 对象。

{
  "instruction": "string" // Instruction for the LLM regarding the purpose of the mcp-playbook.
}

create_spec

在目标项目的 docs/specs/ 目录中创建或覆盖新的规范文件（例如 PRD、RFC、架构规划）。规范文件将按 spec-name.md 的约定命名，并带有序号（例如 0001-initial-design.md）。

参数：

• target_project_dir（string，必填）：目标项目目录根目录的绝对路径或相对路径。
• spec_name（string，必填）：规范文件的名称（不含序号和 .md 扩展名）。会进行基本清理。
• content（string，必填）：规范的 Markdown 内容。

返回： 一个指示成功或失败的 JSON 对象；如果成功，还会包含文件路径。

{
  "status": "success" | "error",
  "path": "string" | undefined, // Path to the created file if successful
  "message": "string" // Description of the result or error
}

create_adr

在目标项目的 docs/adr/ 目录中创建或覆盖新的架构决策记录（ADR）文件。ADR 文件将按 adr-name.md 的约定命名，并带有序号（例如 0001-use-react.md）。

参数：

• target_project_dir（string，必填）：目标项目目录根目录的绝对路径或相对路径。强烈建议使用绝对路径，以提高可靠性。
• adr_name（string，必填）：ADR 文件的名称（不含序号和 .md 扩展名）。会进行基本清理。
• content（string，必填）：ADR 的 Markdown 内容。

返回： 一个指示成功或失败的 JSON 对象；如果成功，还会包含文件路径。

{
  "status": "success" | "error",
  "path": "string" | undefined, // Path to the created file if successful
  "message": "string" // Description of the result or error
}

create_changelog

在目标项目的 docs/changelog/ 目录中创建一份新的、详细且面向用户的变更日志条目文件。每个变更日志条目都应单独存为一个文件，并遵循 changelog-entry.md 命名约定，带有序号（例如，0001-added-new-feature.md）。条目应全面说明变更内容，包括如何使用新功能或其对现有功能的影响，而不是仅提供简短摘要。

参数：

• target_project_dir（字符串，必填）：目标项目目录根目录的绝对路径。强烈建议使用绝对路径，以提高可靠性。
• entry_content（字符串，必填）：新变更日志条目的 Markdown 内容。
• changelog_name（字符串，必填）：变更日志文件的预期名称（不含序号和 .md 扩展名）。

返回： 指示成功或失败的 JSON 对象；成功时包含文件路径。

{
  "status": "success" | "error",
  "path": "string" | undefined, // Path to the updated file if successful
  "message": "string" // Description of the result or error
}

distill_project_runbook

在目标项目中创建或更新中央 docs/runbook.md 文件。LLM 负责：

1. 全面分析 target_project_dir 中所有相关项目文档（ADR、规格说明、变更日志、代码等）。
2. 如果 docs/runbook.md 已存在，在分析过程中审阅其当前内容。
3. 综合所有收集到的信息（包括现有 docs/runbook.md 中的信息），更新并完善项目运行手册。

此工具接收 LLM 生成的内容，并将其保存到 docs/runbook.md，覆盖先前版本。工具负责管理 frontmatter（标题、最后更新时间、提炼来源）。

参数：

• target_project_dir（字符串，必填）：目标项目目录根目录的绝对路径。
• content（字符串，必填）：LLM 生成并综合整理的 docs/runbook.md 文件完整 Markdown 内容。
• source_document_references（字符串数组，可选）：LLM 在最近一次提炼/更新中使用的关键源文档路径或描述性引用数组（例如，[\'docs/adr/0001-auth-decision.md\', \'src/auth/service.ts\']）。

返回： 指示成功或失败的 JSON 对象；成功时包含 docs/runbook.md 的路径。

{
  "status": "success" | "error",
  "path": "string" | undefined, // Path to docs/runbook.md if successful
  "message": "string" // Description of the result or error
}

save_and_upload_chat_log

捕获当前对话历史。如果 MCP 客户端直接提供历史记录，则使用该记录；否则，服务会根据可选的 editorType 参数，或依次尝试各个解析器，从本地安装的受支持编辑器（Cursor、Zed、Cline）中解析聊天日志。随后，将捕获或解析到的历史记录保存为目标项目 .chat/ 目录中一个名称唯一的 Markdown 文件，并上传到 dwarvesf/prompt-log GitHub 仓库。需要提供 userId 以整理日志。

参数：

• target_project_dir（字符串，必填）：目标项目目录根目录的绝对路径，聊天日志将在上传前保存到此目录。强烈建议使用绝对路径，以提高可靠性。
• userId（字符串，必填）：用户/LLM 客户端的唯一 ID（例如，你的 GitHub 用户名）。
• editorType（字符串，可选）：指定要尝试解析聊天历史的编辑器（例如，'cursor'、'zed'、'cline'）；如果客户端未直接提供聊天历史，则从该编辑器解析。若省略，服务可能会尝试检测所有受支持编辑器的日志。

返回： 指示成功或失败的 JSON 对象；成功时包含本地路径、GitHub 路径，以及可能的 GitHub URL。

{
  "status": "success" | "error",
  "local_path": "string" | undefined, // Path to the locally saved file
  "github_path": "string" | undefined, // Path within the GitHub repository
  "github_url": "string" | undefined, // URL of the file on GitHub
  "commit_sha": "string" | undefined, // SHA of the commit if successful
  "commit_url": "string" | undefined, // URL of the commit if successful
  "message": "string" // Description of the result or error
}

search_runbook

在 dwarvesf/runbook GitHub 仓库中模糊搜索关键词。如果关键词包含空格，则会搜索完整短语或单个词。它会返回匹配度最高的 5 个文件及其完整内容，以及 GitHub 找到的匹配总数。服务器运行期间会使用内存缓存，避免对相同查询重复调用 GitHub API。

参数：

• keyword（字符串，必填）：要在 dwarvesf/runbook 仓库中搜索的关键词。

返回值： 包含搜索结果的 JSON 对象。

{
  "results": [ // An array of search results (limited to top 5)
    {
      "path": "string", // The path to the file in the repository
      "snippet": "string", // A snippet of the content where the keyword was found
      "full_content": "string" | null, // The full decoded content of the file, or null if fetching failed
      "url": "string" // The URL to the file on GitHub
    }
  ],
  "total_count": "number", // The total number of results found by GitHub's search
  "message": "string" // A message describing the result of the search, e.g., "Found and processed 5 results out of 10 total."
}

search_prompts

在 dwarvesf/prompt-db GitHub 仓库中模糊搜索关键词（不包括 .synced_prompts/ 文件夹）。

参数：

• keyword（字符串，必填）：要在 dwarvesf/prompt-db 仓库中搜索的关键词（不包括 .synced_prompts/ 文件夹）。

返回值： 包含搜索结果的 JSON 对象。

{
  "results": [ // An array of search results (limited to top 5)
    {
      "path": "string", // The path to the file in the repository
      "snippet": "string", // A snippet of the content where the keyword was found
      "full_content": "string" | null, // The full decoded content of the file, or null if fetching failed
      "url": "string" // The URL to the file on GitHub
    }
  ],
  "total_count": "number", // The total number of results found by GitHub's search
  "message": "string" // A message describing the result of the search, e.g., "Found and processed 5 results out of 10 total."
}

suggest_runbook

在 dwarvesf/runbook 仓库中创建或更新 Pull Request，以添加新的 runbook 条目。

参数：

• content（字符串，必填）：runbook 条目的 Markdown 内容。为便于整理，请在开头添加 frontmatter（--- title: ..., description: ..., date: ..., authors: ..., tags: ... ---）。
• target_folder（字符串，必填）：dwarvesf/runbook 仓库中的指定文件夹。必须是以下之一：technical-patterns、operational-state-reporting、human-escalation-protocols、diagnostic-and-information-gathering、automations、action-policies-and-constraints。
• filename_slug（字符串，可选）：用作文件名的 slug。
• pr_number（数字，可选）：要更新的现有 Pull Request 的编号。
• branch_name（字符串，可选）：用于此次更改的分支名称。建议遵循描述性命名约定（例如：'feat/add-runbook-entry-slug'）。
• commit_message（字符串，可选）：文件更改的提交消息。
• pr_title（字符串，可选）：新 Pull Request 的标题。遵循 commitlint 标准（例如：'feat: add new runbook entry'）。
• pr_body（字符串，可选）：新 Pull Request 的正文内容。请提供全面、详细的说明，解释该 runbook 条目的背景和目的。

返回值： 一个 JSON 对象，指示成功或失败；成功时包含 PR 编号和 URL。

{
  "status": "success" | "error",
  "pr_number": "number" | undefined, // The number of the created or updated Pull Request.
  "pr_url": "string" | undefined, // The URL of the created or updated Pull Request.
  "message": "string" // Description of the result or error
}

sync_prompt

将大模型提示词同步到 dwarvesf/prompt-db GitHub 仓库。

参数：

• projectName（字符串，必填）：提示词所属项目的名称。
• promptName（字符串，必填）：项目中提示词的变量名或逻辑名称。
• promptContent（字符串，必填）：大模型提示词的实际内容。

返回值： 一个 JSON 对象，指示成功或失败；成功时包含 GitHub 路径和 URL。

{
  "status": "success" | "error",
  "github_path": "string" | undefined, // Path within the GitHub repository
  "github_url": "string" | undefined, // URL of the file on GitHub
  "commit_sha": "string" | undefined, // SHA of the commit if successful
  "commit_url": "string" | undefined, // URL of the commit if successful
  "message": "string" // Description of the result or error
}

think

使用此工具思考某件事。它不会获取新信息或对仓库进行任何更改，只会记录想法。在需要复杂推理或头脑风暴时使用。例如，如果你探索仓库并发现了 Bug 的根源，可以调用此工具，构思几种独特的修复方法，并评估哪些更改最简单、最有效。或者，如果你收到了测试结果，可以调用此工具，构思修复失败测试的方法。

参数：

• thought（字符串，必填）：你的想法。

返回值： 包含已处理想法的 JSON 对象。服务器会包装处理程序返回的原始字符串。

{
  "content": [
    {
      "type": "text",
      "text": "\"Your processed thought here\"" // Note: The thought string itself will be JSON stringified
    }
  ]
}

或者，如果发生错误：

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Error: Invalid arguments: Your error message"
    }
  ]
}

设置

本地开发

1. 克隆代码仓库：

   git clone [email protected]:dwarvesf/mcp-playbook.git
   cd mcp-playbook
   

2. 安装依赖：

   npm install
   

3. 构建项目：

   npm run build # This compiles TypeScript to JavaScript in the 'dist' directory
   

4. 配置 GitHub 身份验证（请参阅下文的配置部分）。
5. 运行编译后的服务：

   node dist/src/index.js
   

使用 Docker 运行（可选）

计划中包含 Dockerfile，但此处尚未完全实现。完成后，你可以构建并运行 Docker 镜像：

1. 构建 Docker 镜像：

   docker build -t mcp-playbook .
   

2. 运行容器，并确保传入 GITHUB_PERSONAL_ACCESS_TOKEN 环境变量：

   docker run --pull=always -e GITHUB_PERSONAL_ACCESS_TOKEN="your_token" mcp-playbook
   

配置与测试

save_and_upload_chat_log 工具需要具有 repo 范围的 GitHub Personal Access Token，才能将文件上传到 dwarvesf/prompt-log。必须通过 GITHUB_PERSONAL_ACCESS_TOKEN 环境变量提供此令牌。

本地开发时，你可以在项目根目录中使用 .env 文件：

GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token_here

确保将 .env 添加到 .gitignore 文件中。

测试

运行 npm run build，并更新 MCP 配置，使其指向输出的 index.js 文件。

{
  "mcpServers": {
    "mcp-playbook": {
      "command": "node",
      "args": ["/path/to/your/mcp-playbook/dist/src/index.js"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_github_token_here"
      }
    }
  }
}

使用示例

mcp_mcp-playbook_create_spec(target_project_dir="/Users/monotykamary/VCS/working-remote/my-new-project", spec_name="Initial Design", content="# Initial Design Specification\n\nThis document outlines the initial design of the project...")

故障排除

• 未设置环境变量：确保在运行 mcp-playbook 服务进程的环境中正确设置了 GITHUB_PERSONAL_ACCESS_TOKEN 环境变量。
• 未找到文件/目录：服务在指定的 target_project_dir 中运行。请确保提供的路径存在，且服务进程可以访问。文件系统错误（ENOENT）通常表示路径不正确或目录缺失。
• GitHub API 错误：如果 save_and_upload_chat_log 运行失败，请查看服务日志，了解 githubApi.ts 错误处理中的详细信息。常见问题包括令牌不正确、权限不足或触发速率限制。

提交给其他工程师的交接指南

• **实现自成一体：**此服务使用 Node.js 的 fs 和 node-fetch 直接与文件系统和 GitHub API 交互，而不使用环境提供的外部 commander 或 github 工具。
• **target_project_dir：**所有与用户文件交互的工具都需要并在 target_project_dir 中运行。对此路径进行输入验证对安全至关重要。
• **依赖项：**确保已安装所有 npm 依赖项（npm install）。项目使用 TypeScript；使用 npm run build（或 npx tsc）进行编译。
• **身份验证：**GitHub 身份验证仅依赖于 src/githubApi.ts 中通过 process.env 读取的 GITHUB_PERSONAL_ACCESS_TOKEN 环境变量。
• 对话历史占位符：src/handlers.ts 中的 getConversationHistoryPlaceholder() 函数是一个 虚设实现。必须将其替换为从托管此服务的 MCP 框架中获取实际对话历史的逻辑，save_and_upload_chat_log 工具才能正常工作。
• MCP 框架集成：src/handlers.ts 中的处理函数旨在由外部 MCP 框架调用，该框架接收并路由来自大模型的工具调用。src/index.ts 文件是此集成的概念性入口点。