@yeepay/awesome-components-mcp/.taskmaster/prd.txt

MCP server providing access to awesome-components documentation and integration guides with dual-mode operation: direct fetch and GitLab MCP instruction generation

<context>
# Overview
本项目旨在构建一个名为 `awesome-components-mcp` 的 MCP (Model Context Protocol) Server。该服务器的核心目标是使大型语言模型 (LLM) 能够通过标准化的 MCP 工具，发现可对接的技术组件清单，并获取指定技术组件的详细对接指引文档。它解决了 LLM 在集成外部技术组件时，手动查找和理解对接文档效率低下、易出错的问题，并通过一种灵活的机制（部分情况下指导 LLM 调用另一个 MCP Server `gitlab-mcp`，部分情况下直接提供内容）来实现这一目标。该服务器主要面向需要与一系列预定义技术组件交互的 LLM 及其开发者/部署系统，旨在提升 LLM 应用的开发效率、灵活性和准确性。

# Core Features
以下是 `awesome-components-mcp` 服务器的核心功能：

1.  **组件发现工具 (`components_discovery`)**
    * **功能描述：** 此工具为 LLM 提供所有可用技术组件的清单（即主 `llms.txt` 文件的内容）。其行为模式通过环境变量配置。
    * **重要性：** 使 LLM 能够了解其可以利用的工具范围。
    * **高级工作原理：**
        * **模式一（直接获取）：** 如果配置了 `LLMS_TXT_URL` 环境变量，本工具将直接通过 HTTP GET 请求该 URL，获取主 `llms.txt` 的内容，并将其作为字符串返回。
        * **模式二（指导调用 `gitlab-mcp`）：** 如果 `LLMS_TXT_URL` 未配置，但配置了 `GITLAB_PROJECT_ID` (URL编码的项目路径) 和 `LLMS_TXT_FILE` (主 `llms.txt` 在项目中的路径) 环境变量，本工具将生成一个结构化的JSON指令。该指令告知 LLM 客户端应如何调用 `gitlab-mcp` 服务器上的 `get_file_contents` 工具（使用这些参数及默认分支如 "main"）来获取主 `llms.txt` 的内容。

2.  **获取组件对接指引工具 (`get_components_guide`)**
    * **功能描述：** 此工具为 LLM 提供特定技术组件的详细对接和使用指引文档（通常是另一个 `llms.txt` 文件）。
    * **重要性：** 为 LLM 提供精确的指令或内容，使其能够正确地与目标组件交互。
    * **高级工作原理：**
        * 工具接收一个 `component_path` 参数，该参数可能是指向内部 GitLab 资源的相对路径，也可能是一个外部资源的完整 URL。
        * `awesome-components-mcp` 服务器需判断该路径的性质（例如，通过匹配一个可配置的内部 GitLab 主机名模式，如 `gitlab.yeepay.com`）。
        * **对于内部 GitLab 资源：** 工具的输出是一个结构化的 JSON 指令，告知 LLM 客户端应如何调用 `gitlab-mcp` 服务器上的 `get_file_contents` 工具。指令中需包含 `gitlab-mcp` 的服务地址、工具名 (`get_file_contents`) 以及必要的参数（如从配置中获取的 `project_id`，从输入 `component_path` 转换得到的 `file_path`）。`project_id` 参数需进行 URL 编码。
        * **对于外部 URL 资源：** 工具将直接通过 HTTP GET 请求该 `component_path` URL，获取其 `llms.txt` 文件的内容，并将此内容作为字符串直接返回给 LLM 客户端。

3.  **MCP 服务器合规性**
    * **功能描述：** 确保 `awesome-components-mcp` 服务器本身的实现严格遵循 MCP 规范，并使用官方推荐的 `MCP TypeScript SDK`。这包括正确定义和注册工具、处理 MCP 请求、以及按照 SDK 规范的方式处理和响应错误（例如，当直接获取外部 URL 内容失败时，服务器应抛出异常）。
    * **重要性：** 保证与所有遵循 MCP 规范的 LLM 客户端的互操作性。
    * **高级工作原理：** Node.js 应用程序将利用 `MCP TypeScript SDK` 来定义上述两个工具。它将启动一个 HTTP 服务器，监听传入的 MCP 请求，将这些请求路由到相应的工具逻辑进行处理，并通过 SDK 返回处理结果（内容或指令）或报告错误。

4.  **配置灵活性**
    * **功能描述：** 服务器的关键行为和参数应通过环境变量进行配置。
    * **重要性：** 提高服务器部署的灵活性和适应不同环境的能力。
    * **高级工作原理：** 支持配置项包括：
        * `components_discovery` 的数据源 (`LLMS_TXT_URL` 或 `GITLAB_PROJECT_ID` 与 `LLMS_TXT_FILE` 组合)。

# User Experience
主要用户为大型语言模型 (LLM)，因此用户体验主要体现在 API 交互的清晰度、指令的准确性和内容的正确性上。

* **用户画像：**
    * 主要用户：大型语言模型 (LLM) 客户端。
    * 次要用户（间接）：LLM 应用的开发者或运维人员，他们负责配置 `awesome-components-mcp` 并可能需要理解其输出的指令。

* **关键用户流程（LLM 视角）：**
    * **组件发现流程：**
        1.  LLM 向 `awesome-components-mcp` 发送 `components_discovery` 请求。
        2.  根据服务器配置，LLM 收到：
            * 主 `llms.txt` 的实际内容（如果通过 `LLMS_TXT_URL` 直接获取）。
            * 或，一个 JSON 指令，说明如何调用 `gitlab-mcp` 来获取主 `llms.txt`。若为指令，LLM 需自行执行对 `gitlab-mcp` 的调用。
        3.  LLM 解析获得的列表（或获取列表后的内容），识别可用组件。
    * **组件指引获取流程：**
        1.  LLM 向 `awesome-components-mcp` 发送 `get_components_guide` 请求，并附带组件路径。
        2.  根据组件路径的性质，LLM 收到：
            * 对于内部 GitLab 组件：一个 JSON 指令，说明如何调用 `gitlab-mcp` 获取该组件的 `llms.txt`。LLM 需自行执行对 `gitlab-mcp` 的调用。
            * 对于外部 URL 组件：该组件 `llms.txt` 的实际内容（由 `awesome-components-mcp` 直接获取并返回）。
        3.  LLM 解析获得的指南内容（或获取指南后的内容），理解如何与组件交互。
    * **错误处理流程：**
        * 如果 `awesome-components-mcp` 在直接获取外部 URL 内容时失败（例如网络错误、404），它应抛出符合 MCP 规范的异常。
        * 如果 `awesome-components-mcp` 生成指令，则后续调用 `gitlab-mcp` 的成功或失败由 LLM 客户端自行处理。`awesome-components-mcp` 仅保证其生成的指令在结构上是正确的（基于已知信息）。

* **UI/UX 注意事项：**
    * API 响应（无论是内容还是指令）必须清晰、结构化且易于程序化处理。
    * `README.md` 文档需详细说明服务器的配置方法、两种工具的行为模式、以及输出指令的格式和含义。
</context>
<PRD>
# Technical Architecture
* **系统组件：**
    * **MCP 服务器应用 (Node.js/TypeScript):** 核心应用程序，包含：
        * **MCP 工具定义模块：** 实现 `components_discovery` 和 `get_components_guide` 工具的条件逻辑。
        * **HTTP 客户端模块：** 用于在需要时直接获取外部 URL 的内容。
        * **配置管理模块：** 读取和解析环境变量，决定工具行为。
        * **指令生成模块：** 负责构建发送给 LLM 客户端的、关于如何调用 `gitlab-mcp` 的 JSON 指令。
* **数据模型：**
    * **输出指令模型 (JSON)：** 用于指导 LLM 调用 `gitlab-mcp`，包含 `action_type: "mcp_call"`，`tool_name`，`parameters` 等字段。
    * **输出内容模型：** 对于直接获取的场景，输出为纯文本字符串 (`llms.txt` 内容)。
* **API 与集成：**
    * **入站 API：** 基于 HTTP 的 MCP 协议接口。
    * **出站集成：** 仅在处理外部 URL 时，会发生对这些外部服务器的 HTTP GET 请求。不存在对 `gitlab-mcp` 的直接程序化调用。
* **基础设施需求：**
    * Node.js 运行时环境 (推荐 LTS v20 或更高版本)。
    * 网络访问能力（用于获取外部 URL 内容）。

# Development Roadmap
* **MVP 需求：**
    1.  `components_discovery` 工具：
        * 实现基于 `LLMS_TXT_URL` 的直接内容获取逻辑。
        * 实现基于 `GITLAB_PROJECT_ID` 和 `LLMS_TXT_FILE` 的指令生成逻辑。
        * 正确处理错误（例如，直接获取失败时）。
    2.  `get_components_guide` 工具：
        * 实现基于内部/外部 URL 判断的逻辑分支。
        * 对内部 GitLab 路径，实现调用 `gitlab-mcp` 的指令生成逻辑。
        * 对外部 URL 路径，实现直接内容获取逻辑。
        * 正确处理错误。
    3.  MCP 服务器基础搭建与 SDK 集成。
    4.  完整的配置管理（通过环境变量）。
    5.  `README.md` 文档：包含安装、详细配置、工具行为说明、指令格式示例。
    6.  `package.json`：包含依赖和脚本。
    7.  单元测试与集成测试：覆盖核心逻辑、条件分支、指令生成和外部内容获取。

# Logical Dependency Chain
1.  **基础构建块：**
    * 项目初始化、依赖安装。
    * MCP 服务器核心框架搭建。
    * 配置管理模块（环境变量读取与解析）。
    * HTTP 客户端模块（用于直接获取外部内容）。
2.  **`components_discovery` 工具实现：**
    * 实现直接获取模式 (`LLMS_TXT_URL`)。
    * 实现指令生成模式 (`GITLAB_PROJECT_ID`, `LLMS_TXT_FILE`)。
3.  **`get_components_guide` 工具实现：**
    * 实现内部/外部 URL 的判断逻辑。
    * 实现外部 URL 内容直接获取分支。
    * 实现内部 GitLab 路径指令生成分支。
4.  **测试与文档（并行与迭代）：**
    * 单元测试各模块逻辑。
    * 集成测试模拟 MCP 调用和外部 HTTP 请求。
    * 撰写和完善 `README.md`。
5.  **功能迭代与范围控制：**
    * MVP 聚焦于两种工具在不同模式下的正确行为和清晰指令/内容输出。

# Risks and Mitigations
* **风险：** LLM 客户端可能难以正确解析和执行 `awesome-components-mcp` 生成的指令去调用 `gitlab-mcp`。
* **缓解：** `awesome-components-mcp` 输出的指令格式应尽可能清晰、完整和标准化。`README.md` 中提供详细的指令说明和 LLM 客户端调用示例。
* **风险：** `gitlab-mcp` 服务不可用或其 `get_file_contents` 工具行为与预期不符，将导致通过指令获取内容失败（此部分由 LLM 客户端感知）。
* **缓解：** `awesome-components-mcp` 明确其职责边界，它仅负责生成正确的指令（基于其所知信息）。LLM 客户端需要有自身的容错机制。
* **风险：** `awesome-components-mcp` 直接获取外部 URL 内容时，可能遇到网络问题、目标服务器不可用或内容格式错误。
* **缓解：** 实现健壮的 HTTP 请求逻辑，包括超时、重试（谨慎）、以及明确的错误状态上报（通过 MCP 异常）。
* **风险：** 配置错误（例如 `LLMS_TXT_URL` 不可达，或 `gitlab-mcp` 地址错误）导致服务不可用或行为异常。
* **缓解：** 启动时进行配置校验，提供清晰的配置错误日志。文档中详细说明各配置项含义。

# Appendix
* **技术规格参考：**
    * MCP 规范文档: (用户提供的链接 `https://modelcontextprotocol.io/llms-full.txt`)
    * MCP TypeScript SDK: (用户提供的链接 `https://github.com/modelcontextprotocol/typescript-sdk`)
    * `gitlab-mcp` 的 `get_file_contents` 工具参数 (由用户提供):
        * `project_id` (必需): 项目 ID 或 URL 编码的路径。
        * `file_path` (必需): 文件或目录的路径。
        * `ref` (可选): 获取内容的分支/标签/提交。
* **配置项示例参考 (从用户输入中提炼的核心环境变量)：**
    * `LLMS_TXT_URL`: (可选) 主 `llms.txt` 的直接 URL。
    * `GITLAB_PROJECT_ID`: (可选，与 `LLMS_TXT_FILE` 配合使用) 主 `llms.txt` 所在 GitLab 项目的 URL 编码路径。
    * `LLMS_TXT_FILE`: (可选，与 `GITLAB_PROJECT_ID` 配合使用) 主 `llms.txt` 在项目内的文件路径。
    * `INTERNAL_GITLAB_HOST`: (可选，名称待定) 用于判断内部 GitLab URL 的主机名，例如 `gitlab.yeepay.com`。
</PRD>