上下文索引mcp
用于AI代理的轻量级、零依赖上下文索引MCP服务器。
作者 Marcus Low Wern狗marcuslowwernchien@gmail.com）
______________________________________________________________________
这是什么？
当你构建一个人工智能代理（如个人管家、编码助理或工作流机器人）时，代理会积累大量的上下文文件——指南、凭据参考、工作流文档、注释。问题是：代理不知道那里有什么，也不知道如何快速找到它。
context-index-mcp 用一个简单的关键字解决这个问题→ 文件路径索引作为MCP（模型上下文协议）服务器公开。代理人打电话来 lookup("animeoshi database") 并立即获取要读取的文件路径。没有嵌入，没有向量DB，没有API调用——只有一个JSON文件和一个评分函数。
______________________________________________________________________
运作原理
- 储存： 平原
index.json文件（条目数组） - 运输： stdio（MCP标准）--按需生成，无持久守护进程
- 搜索： 标签、标题和描述字段的关键字评分
- 速度： 每次查找低于1000毫秒
______________________________________________________________________
工具
lookup
按关键字搜索上下文文件。
{
"query": "animeoshi database"
}返回前5个匹配项及其文件路径和读取指令。
______________________________________________________________________
add
在索引中添加或更新条目。用途 file 作为唯一密钥（追加销售）。
{
"title": "AnimeOshi DB Guide",
"file": "context/animeoshi-db-guide.md",
"tags": ["animeoshi", "database", "postgres", "sql", "episodes", "ratings"],
"description": "Schema, credentials, and query examples for the AnimeOshi production DB",
"note": "Updated 2026-04-01 — readonly user confirmed working"
}______________________________________________________________________
list
列出索引中的所有条目。
______________________________________________________________________
remove
按文件路径删除条目。
{
"file": "context/old-guide.md"
}______________________________________________________________________
安装
git clone https://github.com/butler-kasagi/context-index-mcp.git
cd context-index-mcp
npm install建议安装位置：在代理的工作区内，例如。 workspace/mcp-servers/context-index/.
______________________________________________________________________
配置
单一代理——与mcporter合作
添加到您的 config/mcporter.json:
{
"mcpServers": {
"context-index": {
"command": "node",
"args": ["/path/to/context-index-mcp/index.js"]
}
}
}服务器默认为 process.cwd() 作为工作区根目录并查找 index.json 旁边 index.js。如果mcporter是从您的工作区目录启动的，则无需额外配置即可正确解析所有内容。
然后通过以下方式调用工具：
mcporter call context-index lookup --args '{"query":"your search terms"}'
mcporter call context-index add --args '{"title":"...", "file":"context/...", "tags":["tag1","tag2"], "description":"..."}'
mcporter call context-index list多代理设置（共享服务器，单独索引）
在OpenClaw多代理设置中， 每个代理都有自己的工作区目录 以及它自己的 config/mcporter.json关键的见解是：
- 这 服务器二进制文件 (
index.js)居住在一个地方——通常是主代理的工作区 - 每个代理人的
config/mcporter.json指向该共享二进制文件，但通过env变量覆盖工作区和索引路径，因此每个代理都可以读取和写入自己的隔离数据
目录布局（实例）：
~/.openclaw/
├── workspace/ ← Butler (primary agent)
│ ├── config/mcporter.json ← Butler's mcporter config
│ ├── mcp-servers/
│ │ └── context-index/
│ │ ├── index.js ← shared server binary (one copy)
│ │ └── index.json ← Butler's index data
│ └── context/
│ └── *.md ← Butler's context files
│
├── workspace-starrk/ ← Starrk (secondary agent)
│ ├── config/mcporter.json ← Starrk's mcporter config (separate file!)
│ ├── mcp-servers/context-index/
│ │ └── index.json ← Starrk's index data (separate!)
│ └── context/
│ └── *.md ← Starrk's context files
│
└── workspace-agent-c/ ← Agent C (any future agent)
├── config/mcporter.json ← Agent C's mcporter config
├── mcp-servers/context-index/
│ └── index.json ← Agent C's index data
└── context/
└── *.md关键规则： 每个工作区都有自己的 config/mcporter.json这就是每个代理独立的原因——它们共享服务器代码，但具有完全隔离的索引和工作区范围。巴特勒的 ~/.openclaw/workspace/config/mcporter.json:
{
"mcpServers": {
"context-index": {
"command": "node",
"args": ["/Users/you/.openclaw/workspace/mcp-servers/context-index/index.js"]
}
}
}*（不需要env变量——cwd是Butler的工作区，默认情况下index.json位于index.js旁边）*
斯塔克 的 ~/.openclaw/workspace-starrk/config/mcporter.json:
{
"mcpServers": {
"context-index": {
"command": "node",
"args": ["/Users/you/.openclaw/workspace/mcp-servers/context-index/index.js"],
"env": {
"CONTEXT_INDEX_WORKSPACE": "/Users/you/.openclaw/workspace-starrk",
"CONTEXT_INDEX_PATH": "/Users/you/.openclaw/workspace-starrk/mcp-servers/context-index/index.json"
}
}
}
}代理人C ~/.openclaw/workspace-agent-c/config/mcporter.json:
{
"mcpServers": {
"context-index": {
"command": "node",
"args": ["/Users/you/.openclaw/workspace/mcp-servers/context-index/index.js"],
"env": {
"CONTEXT_INDEX_WORKSPACE": "/Users/you/.openclaw/workspace-agent-c",
"CONTEXT_INDEX_PATH": "/Users/you/.openclaw/workspace-agent-c/mcp-servers/context-index/index.json"
}
}
}
}环境变量：
| 变量 | 目的 | 默认值 |
|---|---|---|
CONTEXT_INDEX_WORKSPACE | 文件条目解析的根路径 lookup 结果 | process.cwd() |
CONTEXT_INDEX_PATH | 通往 index.json 数据文件 | index.json 旁边 index.js |
提示： 如果要设置新代理，请创建其index.json作为一个空{"entries":[]}首先，然后使用以下命令填充它mcporter call context-index add对于该代理工作区中的每个上下文文件。
使用OpenClaw
添加到代理 openclaw.json:
{
"mcp": {
"servers": {
"context-index": {
"command": "node",
"args": ["/path/to/context-index-mcp/index.js"]
}
}
}
}对于多代理OpenClaw设置，使用mcporter的per-agent config/mcporter.json 使用env变量（见上文）而不是全局变量 openclaw.json.
使用克劳德桌面/任何MCP客户端
添加到MCP客户端配置中：
{
"mcpServers": {
"context-index": {
"command": "node",
"args": ["/path/to/context-index-mcp/index.js"]
}
}
}______________________________________________________________________
数据格式
index.json 结构：
{
"entries": [
{
"title": "Production DB Guide",
"file": "context/database-guide.md",
"tags": ["database", "postgres", "sql", "schema"],
"description": "Schema and query examples for the production database",
"note": "readonly user, host: db.example.internal",
"updatedAt": "2026-01-01T08:30:00.000Z"
}
]
}这 file 字段是唯一的键。路径是相对于您的工作区根目录的（可在中配置 index.js 通过 WORKSPACE 常数）。
______________________________________________________________________
搜索评分
条目按加权关键字匹配进行排名：
| 比赛类型 | 得分 |
|---|---|
| 标签完全匹配 | +4 |
| 标签包含术语 | +2 |
| 标题包含术语 | +2 |
| 描述包含术语 | +1 |
然后，分数乘以与至少一个字段匹配的查询词的分数，惩罚只与5个搜索词中的1个匹配的条目。
______________________________________________________________________
为什么不使用矢量数据库？
对于个人代理的上下文索引（数十到数百个文件），语义搜索是多余的：
- 不需要API密钥
- 无嵌入延迟
- 完全离线
- 代理控制标签，所以精度很高
如果你使用模糊自然语言查询扩展到数千个条目，那么向量存储就更有意义了。
______________________________________________________________________
上下文文件模式
这个工具的真正力量来自于将索引与 上下文文件 --记录您的工作流程、工具、凭据参考和SOP的普通标记文件。索引只是查找层；内容存在于文件中。
它在实践中是如何工作的
your-workspace/
├── context/
│ ├── deploy-to-production.md ← step-by-step deploy workflow
│ ├── database-guide.md ← schema, connection info, query examples
│ ├── n8n-publishing-workflow.md ← how to publish HTML via n8n webhook
│ ├── slack-channel-ids.md ← channel IDs, bot config
│ └── onboarding-checklist.md ← new team member steps
└── index.json ← the index pointing to all of the above当代理需要部署某些东西时，它不必猜测或产生幻觉——它会查找 "deploy production"，获取文件路径，读取确切步骤。
上下文文件中有什么？
一个好的上下文文件会回答： *“如果我是一名从头开始这项任务的新工程师，我需要知道什么？”*
示例-- context/deploy-to-production.md:
# Deploy to Production Guide
## SSH Access
Host: 203.0.113.10 ← replace with your server IP
User: deploy
Key: ~/.ssh/id_ed25519
## Steps
1. SSH into the instance
2. cd /home/godju/app && git pull origin main
3. pm2 restart app
4. Verify: curl https://api.example.com/health
## Rollback
git checkout
&& pm2 restart app
## Notes
- Always pull before restarting — never edit files directly on the server
- If pm2 is not running: pm2 start ecosystem.config.js示例-- context/database-guide.md:
# Production Database
## Connection
Host: db.example.internal:5432
DB: myapp
User: readonly
Password: (stored in connections.md — never commit)
## Key Tables
- public.anime — anime metadata, mal_id, title, release_year
- public.episodes — episode list per anime
- anime.episode_ratings — user ratings per episode
## Common Queries
-- Top rated episodes this week
SELECT e.title, AVG(r.rating) as avg_rating, COUNT(*) as votes
FROM anime.episode_ratings r
JOIN public.episodes e ON e.id = r.episode_id
WHERE r.created_at > NOW() - INTERVAL '7 days'
GROUP BY e.id ORDER BY avg_rating DESC LIMIT 10;______________________________________________________________________
指导您的AI代理
安装后，将这些说明添加到代理的系统提示或工作区配置文件中（例如。 AGENTS.md, CLAUDE.md，或您代理的内存文件）：
最少指令
## Context Index
Before performing any task, if you need workflow steps, credentials references,
or tool documentation, search the context index first:
mcporter call context-index.lookup query=""
This returns a file path. Read that file for exact instructions.
Always index new workflows you create:
mcporter call context-index.add \
title="..." file="context/xxx.md" tags='["tag1","tag2"]' description="..."完整说明（推荐）
## Context Index (Fast Lookup)
Primary tool for finding context files — use this FIRST before guessing.
mcporter call context-index.lookup --args '{"query":""}'
Returns file paths instantly. Examples:
- "deploy production ssh" → context/deploy-to-production.md
- "database schema queries" → context/database-guide.md
- "n8n webhook publish html" → context/n8n-publishing-workflow.md
**When creating new context files — ALWAYS index them:**
mcporter call context-index.add --args '{
"title": "...",
"file": "context/xxx.md",
"tags": ["tag1", "tag2"],
"description": "One-line summary of what this file contains"
}'
Never leave a workflow undocumented. If you figure out how to do something
non-obvious (SSH access, API quirks, deploy steps, tool configs), write it
to a context file and index it immediately. Future sessions will thank you.代理提示流示例
用户询问： *“将最新版本部署到生产环境”*
代理流：
context-index.lookup("deploy production")→ 回报context/deploy-to-production.md- 代理读取文件→ 获取确切的SSH主机、命令、回滚步骤
- 自信地执行——没有幻觉般的路径或错误的标志
______________________________________________________________________
用户询问： *“查询本周有多少用户对剧集进行了评分”*
代理流：
context-index.lookup("database episode ratings query")→ 回报context/database-guide.md- 代理读取文件→ 获取连接详细信息+示例SQL
- 使用正确的凭据和表名运行查询
______________________________________________________________________
客服刚刚想出了一个新的工作流程：
代理流：
- 写
context/new-workflow.md记录步骤 context-index.add(title="...", file="context/new-workflow.md", tags=[...], description="...")- 下一环节：工作流可以立即找到——零上下文丢失
______________________________________________________________________
许可证
麻省理工学院