mcp-server-guide

# MCP Guide Server 这个MCP服务器提供了一套指令和文档的存储库。它支持迭代和分阶段的开发周期，以帮助开发者构建软件功能。 ## 这个 MCP Server 是用来做什么的？ 这个 MCP 不仅仅是为了开发者的便利。它集中管理 AI 代理指令的提供，无论你使用的是哪个客户端。它应该能够与任何支持 MCP 服务器的代理一起工作。 ## 背景 指令和提示是以受控、有效和富有成效的方式使用代理人工智能（agentic AI）的**关键**部分。所谓的“氛围编码”（vibe coding）仅对一小部分任务有用，例如简单的命令行工具或脚本。一旦进入更复杂的应用，即使是小型应用，上下文窗口和其他因素使得这种方法容易出错，架构往往显得支离破碎且过度设计，混合了不同的关注点，并基于猜测和模糊性做出错误决策。 在受控的方式下使用时，可以使结果更加确定。 由于我使用多个代理（通常在前三个之间切换），我需要一个共同的地方来存储提示和指令。最初，我使用分散在各个目录中的文档，但这变得难以管理，有时需要在目录之间复制文件，并尝试在改进时保持它们的更新。 每个代理客户端对指令的来源都有自己的看法，同一供应商的某些实现或版本之间往往存在不一致或缺乏一致性。`mcp-server-guide`是我的解决方案。它将提示和指令保存在一个中心位置，并可以将它们与项目本身分开。 ## 目标 提示是保持一个自主代理在工作指南内的关键。没有它们，代理将根据温度和其 LLM（大语言模型）的调优，通常会执行你的指令加上一些额外的内容。当提供一个想法时，代理会立即开始进行更改，尽管它只有不完整的上下文、对过去事件的知识，并且常常对重复代码、破坏封装或以与代码库其他地方完全不同的方式实施更改几乎不予考虑。 这个 MCP 是朝着为 AI 提供无法（或不应该）忽视的保护措施迈出的一步，旨在提供更确定的行为和输出。这个解决方案并不能保证，AI 有时会完全忽视指令。 ### 实现 `mcp-server-guide` 支持内置的迭代开发周期。它旨在遵循一个四步流程，使用以下阶段： **讨论**：此阶段用于指定需求，以及最终完成要实现的功能所需满足的条件。用户和代理都需要在此阶段达成一致。用户明确需要完成的任务——通常还包括如何完成——而代理需要清楚理解。在实施过程中可能出现的所有问题在此时可能无法充分覆盖（或发现），但任何已知的假设都应被陈述。 **规划**：显而易见，规划阶段就是为了规划。此阶段的目标是生成以规范文档、实施计划和/或检查清单的形式呈现的资产——或者根据用户的偏好，将三者合并为一个文档。文档以 markdown 格式生成，以便用户和代理都能方便阅读。在过渡到下一个阶段之前，用户必须明确提供同意，这本质上是对文档内容的认可。 > 在此阶段生成文档工件的原因提供了几个好处： > - 计划不需要立即执行 > - 计划可以暂停并恢复 > - 多个计划可以排队、重新排序并随着时间的推移进行增强 > - 这是关于功能实现的参考点 **实施**：此阶段需要用户的明确同意，代理在此阶段执行计划。必须坚持要求代理定期在检查清单上标记已完成的项目，并标记任何被推迟或“待办”的事项。必须在每个单独任务之前（在 TDD 模式下）生成并运行测试，以确保生成的代码按预期工作。 **检查**：在此阶段运行自动化软件检查，以确保符合项目标准。这也提供了代码审查的机会；确保实现符合用户的意图，符合并完成实施计划，并与整体项目架构一致。 阶段之间的过渡不是自动的，而是在满足某些条件时触发，例如 `.consent` 和 `.issue` 文件的存在及其内容。也不要求严格的顺序。可以使用 `@guide` 提示强制过渡到用户认为应适用的任何阶段。 ## 快速安装 **前提条件：** 首先安装 `libmagic` 系统库： - macOS: `brew install libmagic` - Ubuntu/Debian: `sudo apt-get install libmagic1` - Fedora/RHEL: `sudo dnf install file-libs` - Windows: `choco install file` 有关详细的安装说明，请参见 [INSTALLATION_GUIDE.md](INSTALLATION_GUIDE.md)。 使用支持 JSON 配置的代理快速入门： ```json { "mcpServers": { ... "mcp-server-guide": { "command": "uvx", "args": ["mcp-server-guide"], "env": { "GUIDE_TOOL_PREFIX": "" } } ... } } ``` 注意：您需要在操作系统中安装 `uv` 以使 `uvx` 命令可用。 ### 初始设置 安装后，服务器将在新项目开始时自动创建默认类别。您可以使用下面描述的管理功能自定义配置。 ### 环境变量 - `GUIDE_TOOL_PREFIX`: 控制工具名称前缀（默认值："guide_"） - `GUIDE_PROJECT_NAME`: 覆盖默认项目检测 - `GUIDE_CONFIG_PATH`: 自定义配置文件路径 ### 使用 @guide 的第一步 连接到您的 AI 客户端后，尝试以下命令： ``` @guide help # 显示详细的帮助信息 @guide category list # 列出可用的类别 @guide guide # 显示一般指南 @guide lang python # 显示 Python 特定的指南 ``` ## 核心用法 ### @guide 提示 - 主要接口 `@guide` 提示是您访问文档和管理开发工作流程的主要接口。 #### 基本命令 ``` @guide help # 显示详细帮助和可用类别 @guide category_name # 显示特定类别的内容 @guide collection_name # 显示特定集合的内容 ``` #### 阶段命令 使用阶段命令控制您的开发工作流程： ``` @guide discuss "topic" # 开始讨论阶段并提供上下文 @guide plan "feature" # 开始规划阶段并提供任务细节 @guide implement # 开始实施阶段 @guide check # 开始检查/验证阶段 ``` #### 类别访问 按类别访问文档： ``` @guide guide # 一般开发指南 @guide lang # 语言特定指南 @guide context # 项目特定信息 @guide prompt # 自定义AI提示 ``` #### 集合访问 集合将多个类别组合在一起以便于访问： ``` @guide backend # 访问与后端相关的类别 @guide frontend # 访问与前端相关的类别 @guide testing # 访问与测试相关的类别 ``` #### 类别连接 一次引用多个类别： ``` @guide api,database,auth # 组合多个类别 @guide lang,guide # 语言指南 + 一般指南 ``` ## 管理功能 ### AI 助手替代方案 与其记住复杂的语法，不如直接问 AI 应该怎么做： - *"创建一个包含 'api' 和 'database' 类别的集合"* - *"显示我所有可用的类别"* - *"移除旧的 'legacy' 类别"* AI 将使用适当的管理工具来满足您的请求。 ### 类别管理 管理您的文档类别： ``` @guide category list # 列出所有类别 @guide category add --name "testing" --dir "tests/" --patterns "*.test.js,*.spec.js" @guide category update --name "testing" --description "测试文件和文档" @guide category remove --name "old-category" ``` ### 集合管理 将类别分组到集合中： ``` @guide collection list # 列出所有集合 @guide collection add --name "backend" --categories "api,database,auth" @guide collection update --name "backend" --categories "api,database,auth,logging" @guide collection remove --name "old-collection" ``` ### 文档管理 在类别中管理特定文档： ``` @guide document list --category "docs" # 列出类别中的文档 @guide document add --category "docs" --name "readme" --content "# 项目 README" @guide document update --category "docs" --name "readme" --content "# 更新后的 README" @guide document remove --category "docs" --name "old-doc" ``` ## 高级功能 ### 集合与类别连接 **集合** 提供了一种强大的方式来组织相关文档： - 将多个类别组合在一起以便于访问 - 创建逻辑分组，如 "backend"（后端）、"frontend"（前端）、"testing"（测试） - 通过单个命令访问全面的上下文 - 适用于组织相关文档（例如，"backend" 集合包括 "api"、"database"、"auth" 类别） **类别连接** 允许引用多个类别： - 使用逗号分隔的类别名称： `@guide api,database,auth` - 组合所有指定类别的内容 - 在提供全面上下文的同时保持逻辑组织 - 非常适合需要多个知识领域的复杂任务 ### 文档管理与基于模式的内容 系统支持两种类型的内容： #### 基于模式的内容 - 按类别模式匹配的文件（例如，类别目录中的 `*.md` 文件） - 基于文件模式自动发现 - 当文件从目录中添加/移除时会发生变化 - 动态并反映当前文件系统状态 #### 管理文档 - 通过文档管理功能创建的特定文档 - 不受模式匹配的影响 - 可以直接引用类别/文档名称，无需模式匹配 - 在明确删除之前保持持久 - 适合稳定的、经过策划的内容 ### 项目管理 在不同项目和配置之间切换： ``` @guide project list # 列出可用的项目 @guide project switch "my-project" # 切换到另一个项目 @guide project config # 显示当前项目配置 ``` ## 配置 ### 命令行选项 | 短选项 | 长选项 | 描述 | | ------ | ------------------ | ----------------------------------------------------------- | | `-c` | `--config` | 配置文件路径 | | `-d` | `--docroot` | 文档根目录（默认: `.`） | | `-C` | `--log-console` | 启用控制台日志记录（默认: 除非指定文件，否则为真） | | `-N` | `--no-log-console` | 禁用控制台日志记录 | | `-F` | `--log-file` | 日志文件路径（为空表示不记录日志） | | `-J` | `--log-json` | 启用以JSON结构记录日志到文件 | | `-L` | `--log-level` | 日志级别（DEBUG, INFO, WARN, ERROR, OFF） | | `-v` | `--version` | 显示版本并退出 | | `-h` | `--help` | 显示帮助信息并退出 | ### 配置文件 创建一个 YAML 配置文件以自定义行为： ```yaml docroot: "~/.config/mcp-server-guide/docs" projects: my-project: categories: guide: dir: "guide/" patterns: - "*.md" description: "一般开发指南" lang: dir: "lang/" patterns: - "*.md" description: "语言特定指南" collections: backend: categories: - "api" - "database" - "auth" description: "后端开发资源" ``` ### 默认类别 在项目首次实例化时，会创建以下默认类别： - **guide**: 一般开发者指南（TDD 方法论、编码标准、工作流程要求） - **lang**: 编程语言特定指南（语法、最佳实践、工具、项目结构） - **context**: 项目特定信息（问题管理、规范、工作流程细节） - **prompt**: 由各种内置 `@guide` 命令显示的 AI 提示 这些都是可以通过管理功能进行自定义、删除或重命名的常规类别。`prompt` 类别是特殊的，因为它会检查与 `@guide` 命令对应的文件；否则，将使用内置默认值。 ## 示例与工作流程 ### 设置新项目 1. **安装并配置** AI 客户端中的 MCP 服务器 2. **初始化项目类别**： ``` @guide category add --name "api" --dir "src/api/" --patterns "*.js,*.ts" @guide category add --name "tests" --dir "tests/" --patterns "*.test.js" ``` 3. **创建集合**以进行逻辑分组： ``` @guide collection add --name "backend" --categories "api,database" ``` 4. **添加项目特定的文档**： ``` @guide document add --category "context" --name "setup" --content "# 项目设置说明" ``` ### 开发工作流程 1. **从指南开始**: `@guide guide` 以了解项目细节 2. **获取语言设置**: `@guide lang python` 获取Python特定的最佳实践 3. **项目背景**: `@guide context` 以了解项目细节 或者，你可以将所有三个内容组合成一个集合，并通过 `@guide <collection>` 一次性提供它们。 4. **使用阶段命令** 进行结构化开发： - `@guide discuss "新功能实现"` - `@guide plan "用户认证系统"` - `@guide implement` （在计划批准后） - `@guide check` （用于验证和审查） ### 管理文档 1. **定期更新**：保持类别和文档与您的项目同步 2. **使用集合**：将相关类别分组以便于访问 3. **利用AI助手**：请AI帮助管理您的文档结构 4. **模式与管理**：对动态内容使用模式，对稳定参考使用管理文档 ## Docker 部署 对于容器化部署，提供了 Docker 镜像： ```bash ``` # 生产容器（最小占用） docker compose up mcp-server-guide-prod ``` ### 环境变量 - `MCP_LOG_LEVEL`: 设置日志级别（默认：生产环境为 `info`，开发环境为 `debug`） 有关详细的 Docker 配置，请查看仓库中的 `Dockerfile.dev` 和 `Dockerfile.prod` 文件。 有关技术文档和 API 详情，请参见 [API.md](API.md)。