Context Index MCP

上下文索引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"
      }
    }
  }
}

环境变量：

提示： 如果要设置新代理，请创建其 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 常数）。

______________________________________________________________________

搜索评分

条目按加权关键字匹配进行排名：

然后，分数乘以与至少一个字段匹配的查询词的分数，惩罚只与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.

代理提示流示例

用户询问： *“将最新版本部署到生产环境”*

代理流：

1. context-index.lookup("deploy production") → 回报 context/deploy-to-production.md
2. 代理读取文件→ 获取确切的SSH主机、命令、回滚步骤
3. 自信地执行——没有幻觉般的路径或错误的标志

______________________________________________________________________

用户询问： *“查询本周有多少用户对剧集进行了评分”*

代理流：

1. context-index.lookup("database episode ratings query") → 回报 context/database-guide.md
2. 代理读取文件→ 获取连接详细信息+示例SQL
3. 使用正确的凭据和表名运行查询

______________________________________________________________________

客服刚刚想出了一个新的工作流程：

代理流：

1. 写 context/new-workflow.md 记录步骤
2. context-index.add(title="...", file="context/new-workflow.md", tags=[...], description="...")
3. 下一环节：工作流可以立即找到——零上下文丢失

______________________________________________________________________

许可证

麻省理工学院