Resource Provider MCP

资源提供者mcp

   

一个MCP服务器，为LLM提供对Markdown文档的结构化访问。LLM不会浏览原始文件，而是获得一个分层目录，其中每个资源都有元数据，告诉它们包含什么以及何时加载。

为什么存在

使用LLM时，您希望他们快速找到正确的文档，而无需将所有内容加载到上下文中。此MCP通过向文档添加元数据并提供有选择地搜索和加载的工具来解决这个问题。

与单个index.md文件相比

一个大的index.md文件会浪费上下文。如果你需要一个关于身份验证的部分，你仍然可以加载整个50KB的文件。使用此MCP，您只需加载所需的部分。

此外，平面文件没有元数据。法学硕士如果不先阅读所有内容，就无法判断什么是重要的。

与LLM直接浏览文件相比

直接文件系统访问意味着LLM必须猜测要读取哪些文件。它列出目录，按名称选择文件，读取内容以查看是否相关。这很昂贵，而且会暴露你可能不想暴露的文件。

此MCP将发现与检索分开。首先列出带有元数据的资源，然后只加载重要的资源。

安装

npx resource-provider-mcp

或者，您可以直接在配置中将其注册为mcp。

{
  "mcpServers": {
    "resource-provider": {
      "command": "npx",
      "args": ["-y", "resource-provider-mcp"],
      "workingDirectory": "."
    }
  }
}

配置

设置 MCP_RESOURCES_DIR 环境变量指向您的文档根目录。

您可以使用绝对路径或相对路径：

绝对路径：

{
  "mcpServers": {
    "resource-provider": {
      "command": "npx",
      "args": ["-y", "resource-provider-mcp"],
      "env": {
        "MCP_RESOURCES_DIR": "/Users/you/projects/my-app/docs"
      }
    }
  }
}

相对路径：

{
  "mcpServers": {
    "resource-provider": {
      "command": "npx",
      "args": ["-y", "resource-provider-mcp"],
      "workingDirectory": "/Users/you/projects/my-app",
      "env": {
        "MCP_RESOURCES_DIR": "./docs"
      }
    }
  }
}

从当前工作目录解析相对路径。如果您指定 workingDirectory，从该目录解析相对路径。

设置文档

此MCP按三个级别组织文档：上下文（目录）、文件和节（标题）。每个级别都可以有元数据。

创建资源

资源是一个目录，其中包含 resource.json 文件。其中的所有文件都继承其元数据。

创建目录结构：

my-docs/
├── api/
│   └── resource.json
└── guides/
    └── resource.json

在 api/resource.json:

{
  "description": "API documentation and reference",
  "whenToLoad": "When working with the API",
  "importance": "high"
}

在 guides/resource.json:

{
  "description": "User guides and tutorials",
  "whenToLoad": "When learning the system",
  "importance": "mid"
}

添加Markdown文件

放 .md 资源目录中的文件。如果要覆盖资源元数据，请在顶部添加元数据：

api/authentication.md:

# Authentication

This guide covers authentication methods...

## OAuth Setup

Configure OAuth like this...

## API Keys

Generate API keys from...

元数据注释必须位于文件的最顶部，在任何内容之前。

添加节元数据

您可以通过在标题后添加注释来向各个部分添加元数据：

## OAuth Setup

OAuth setup requires...

元数据字段

所有字段都是可选的：

• description：简要说明其中包含的内容
• whenToLoad：LLM应在何时加载此资源（也可以使用小写 whentoload)
• importance: low, mid，或 high （引导加载优先级，也可以使用 priority)

元数据优先级：节>文件>上下文（更具体的覆盖更不具体）。

文件结构示例

以下是一个完整的示例：

my-docs/
├── api/
│   ├── resource.json
│   ├── authentication.md
│   ├── endpoints.md
│   └── errors.md
├── guides/
│   ├── resource.json
│   ├── quickstart.md
│   └── advanced.md
└── internal/
    ├── resource.json
    └── architecture.md

这会创建以下ID：

• api （上下文）
• api|authentication （文件）
• api|authentication|oauth_setup （第节）
• guides|quickstart （文件）
• internal|architecture （文件）

包含哪些内容

MCP仅暴露：

• 目录与 resource.json 文件
• .md 这些目录中的文件
• 这些文件中的章节（标题） .md 文件

没有元数据注释的文件仍然包含在内，它们只是没有描述、何时加载或重要性字段。

嵌套资源

您可以嵌套资源：

docs/
├── resource.json
└── api/
    ├── resource.json
    └── auth.md

这 api 目录是一个嵌套的资源。其ID将是 docs|api。身份验证文件将是 docs|api|auth.

测试您的设置

构建后，直接测试工具：

列出所有内容：

npm run tool:getAvailableResources '{}'

获取特定资源：

npm run tool:getResourceContent '{"id":"api|authentication"}'

搜索资源：

npm run tool:findResourceByPhrases '{"phrases":["authentication"]}'

这些命令直接使用工具，无需经过MCP，这对于调试文档结构非常有用。

工具使用建议

MCP提供了三种具有不同用例的工具：

• findResourceByPhrases：最适合查找特定主题或功能。当你知道你在找什么时，使用这个。
• getAvailableResources：非常适合探索和查看可用内容。使用分页（默认每页15个项目），可以自由使用。然而，当你想到特定的主题时，搜索会更有效。
• getResourceContent：加载特定资源的实际内容。

推荐工作流程：对于特定主题，请先使用搜索。对于探索和发现，列表资源完全可以分页。

良好文档的提示

1. 使用清晰的描述：LLM使用这些来决定加载什么。“API身份验证方法”比“Auth stuff”更好。

1. 正确设置重要性：将关键文档标记为 high，有用的文档 mid，以及参考文件 low.

1. 当加载文本时写得很好：这将指导LLM。“设置身份验证时”或“调试错误时”效果良好。

1. 逻辑组织：将相关文档分组到同一上下文中。尽可能保持层次结构浅。

1. 分割长文件：如果一个文件有多个主题，请考虑将其拆分或添加节元数据，以便LLM可以仅加载相关节。

1. 使用描述性标题：节名称将成为ID的一部分。“OAuth安装程序”比“安装程序”更好。

LLM说明

安装此MCP后，从复制内容 AGENTS_EXAMPLE.md 根据您代理人的指示文件。这将教会LLM如何有效地使用资源提供者工具。

这 AGENTS_EXAMPLE.md 文件包含：

• 所有三个工具（getAvailableResources、findResourceByPhrases、getResourceContent）的详细说明
• 高效资源发现和加载的最佳实践
• 工作流示例和常见模式
• 关于何时以及如何使用每种工具的指南

此文件包含在npm包中，可以在安装后找到。

运作原理

MCP服务器：

1. 扫描您的文档目录以查找 resource.json 文件（上下文）
2. 查找全部 .md 这些目录中的文件
3. 解析文件和节中的元数据注释
4. 使用以下ID构建分层目录 context|file|section
5. 公开了三个用于列出、搜索和加载资源的工具

当LLM调用工具时，服务器只返回请求的内容。清单仅显示元数据，加载显示内容。

故障排除

MCP未连接

常见问题：

• dist/index.js的路径错误
• 通往RESOURCE_BASE_DIR的路径错误
• Node.js不在PATH中
• 构建未运行（忘记 npm run build)

没有资源显示

确保：

• 您的文档目录包含以下目录 resource.json 文件
• 这 RESOURCE_BASE_DIR 路径是正确和绝对的
• 你至少有一个 .md 资源目录中的文件

元数据不工作

检查：

• 元数据注释位于文件的最顶部（用于文件元数据）
• 元数据注释位于标题之后（用于节元数据）
• 评论用途 `` 格式
• 字段名称拼写正确(description, whenToLoad, importance)
• resource.JSON中的JSON有效

搜索未找到资源

记得：

• 搜索仅限于整个单词。“config”与“configuration”不匹配
• 所有短语必须匹配
• 搜索不区分大小写

许可证

麻省理工学院

作者

克日什托夫·苏尔迪