Contextful MCP

情境化mcp

与项目无关的MCP服务器，用于角色加载、文档搜索、代码搜索和缓存测试执行。提供编码代理 按需、分级访问 在会话开始时，无需预先加载整个上下文窗口。

代币节省

在26个文件上测量，v0.4.02026-04-06。跑 bun benchmark.js --update-readme 再生。

看 docs/benchmarks.md 方法论。

______________________________________________________________________

推荐的工作流程

1. get_status --检查哪些功能可用，以及角色是否已经处于活动状态。
2. list_personas → load_persona --为您的任务选择并安排合适的专家。
3. search_docs --在打开完整文件之前拉取目标文档部分。
4. search_code --在读取完整文件之前找到相关的代码块。
5. 使用 get_doc / get_code_file 只有当你需要完整的内容时。

______________________________________________________________________

配置

已配置 专门地 通过环境变量——没有配置文件或CLI参数。

在中设置变量 env 你的块 .mcp.json （或等效的主机配置）。\ 省略变量 禁用相应功能 并完全移除其工具。

所有环境变量

CONTEXTSERVER_TEST 对象字段

示例 .mcp.json --单一回购

{
  "mcpServers": {
    "contextful-mcp": {
      "type": "stdio",
      "command": "/path/to/contextful-mcp.exe",
      "env": {
        "CONTEXTSERVER_REPOROOT": ".",
        "CONTEXTSERVER_DOCSLOCATIONS": "[\"./docs\"]",
        "CONTEXTSERVER_PERSONASLOCATIONS": "[\"./agent_personas\"]",
        "CONTEXTSERVER_CODELOCATIONS": "[\"./src\"]",
        "CONTEXTSERVER_TEST": "{\"hashLocations\":[\"./src\",\"./tests\"],\"commands\":[\"bun test\"],\"hashExtensions\":[\".js\",\".ts\"]}"
      }
    }
  }
}

示例——多个文档和代码目录

在JSON数组中提供多条路径。所有这些都被合并到一个可搜索的索引中。

"CONTEXTSERVER_DOCSLOCATIONS": "[\"./docs\", \"./packages/core/docs\", \"./packages/api/docs\"]",
"CONTEXTSERVER_CODELOCATIONS": "[\"./src\", \"./packages/core/src\", \"./packages/api/src\"]"

示例——多仓库（为两个单独的项目建立索引）

使用绝对路径同时对来自多个存储库的源进行索引。\ 这 directory= 过滤入 search_code 让代理将查询范围限定到特定的仓库。

"CONTEXTSERVER_REPOROOT": "/home/user/projects/backend",
"CONTEXTSERVER_CODELOCATIONS": "[\"/home/user/projects/backend/src\", \"/home/user/projects/frontend/src\"]",
"CONTEXTSERVER_DOCSLOCATIONS": "[\"/home/user/projects/backend/docs\", \"/home/user/projects/frontend/docs\"]"

提示： 使用 search_code(query, directory="backend/") 或 search_code(query, directory="frontend/") 限制结果。

示例-索引外部URL（例如API参考文档）

提取的页面被剥离HTML，分割成多个部分，并在 search_docs 结果。

"CONTEXTSERVER_URLS": "[\"https://developers.cloudflare.com/workers/runtime-apis/\", \"https://bun.sh/docs/bundler\"]",
"CONTEXTSERVER_URL_TTL": "3600"

示例——Python/Go项目

"CONTEXTSERVER_CODE_EXTENSIONS": "[\".py\", \".pyi\"]",
"CONTEXTSERVER_BLOCK_SIZE": "50"

______________________________________________________________________

工具参考

工具是有条件注册的——只有那些配置了功能组的工具才会出现在代理的工具列表中。

始终可用

Persona工具-需要 CONTEXTSERVER_PERSONASLOCATIONS

文档工具——需要 CONTEXTSERVER_DOCSLOCATIONS （或 CONTEXTSERVER_URLS)

代码搜索工具--必需 CONTEXTSERVER_CODELOCATIONS

测试工具——需要 CONTEXTSERVER_TEST

______________________________________________________________________

备注

• 锁定文件（例如。 bun.lock, package-lock.json)和压缩文件(.min.js)自动从代码索引中排除。
• 多个目录中重复的角色或文档名称会向stderr发出警告；最后加载的文件获胜。
• Hot reload监视配置的位置以进行更改，并重建索引（取消2秒）。 CONTEXTSERVER_WATCHLOCATIONS 默认为所有内容位置的联合，因此很少需要显式设置。
• 数组env变量中的所有路径都可以是绝对路径，也可以是相对于 CONTEXTSERVER_REPOROOT.
• CONTEXTSERVER_URLS 内容在启动时和每次热重新加载时（在TTL内）获取。在获取失败时，将保留之前缓存的内容。