Context Finder MCP

上下文MCP

语义代码导航 为AI代理构建：一个来电，一个 有界的 打包——旨在让人感觉像代理人的“项目记忆”，而不是一堆 rg/cat/grep 步骤。

如果你厌倦了“搜索”→ 打开文件→ 再次搜索→ 也许是正确的功能？“，Context将查询转换为紧凑、有界的包-- 本地代理 .context 通过MCP发送纯文本，以及 通过命令API的contract-first JSON （CLI/HTTP/gRPC），当您需要严格的程序化解析时。

从这里开始

• 每日“项目记忆”用户体验： docs/AGENT_MEMORY.md (read_pack 剧本）
• 安装+运行+集成： docs/QUICK_START.md
• 用户体验/产品目标： PHILOSOPHY.md
• 优质闸门（防止退化）： docs/QUALITY_CHARTER.md
• 回购结构+硬规则（针对代理商）： REPO_RULES.md
• 我们如何在不破坏信任的情况下发货： docs/RELEASE_TRAIN.md
• 不同版本的行为差异： CHANGELOG.md

Agent UX：“项目记忆”（重点）

上下文意味着 比外壳探测更方便 *刻意为之*:

• 日常使用的一个入口点： read_pack （MCP）是“上下文的应用补丁”：一个调用在一个预算下返回稳定的项目事实+相关片段。
• 事实优先+预算优先： 响应以compact开头 project_facts 并严格遵守 max_chars.
• 锚定片段： 内存包试图跳到长文档/配置（测试/运行/配置标题）中最有用的部分，而不仅仅是文件的顶部。
• 光标第一个延续： 如果不合适，你继续 cursor — read_pack 支持仅游标连续，游标保持紧凑（需要时由服务器支持），以避免破坏上下文窗口。
• 默认情况下，噪波为零： 默认 response_mode: "facts" （或 "minimal")主要保持产量 *项目内容*，而不是工具喋喋不休。
• 安全默认值： 根锁定文件IO+保守秘密denylist；隐藏的配置仅通过allowlist进行索引（并非偶然 .env 泄漏；通过以下方式选择加入 allow_secrets: true 当你明确需要它时）。
• 多代理友好： 默认情况下，共享MCP后端（一个热引擎缓存+跨多个会话的游标存储）。在共享守护进程模式下，服务器 失败关闭 如果它不能解析单个项目根（不能从相对提示中猜测），以防止跨项目污染。集 CONTEXT_MCP_SHARED=0 只有当您明确需要一个隔离的每会话服务器时（在测试中最有用）。

你得到的

• 代理第一输出： MCP工具返回单个有界值 .context 有效载荷 max_chars （高有效载荷密度，低刀具颤振）。
• 按需图例： 主控程序 help 解释说 .context 信封(A:/R:/N:/M:); [LEGEND] 仅由发射 help 以保持其他工具的低噪音。
• 帮助主题： help {"topic":"tools"} 列出工具清单； help {"topic":"cheat"} 是一个快速使用备忘单； help {"topic":"budgets"} 解释推荐 max_chars 预设。
• 一次呼叫编排： 主控程序 batch 在一个边界下运行多个工具 .context 响应（每个项目部分成功）。用于机器可读的批处理和 $ref 工作流，使用命令API batch.
• 安全文件读取： 主控程序 cat 返回一个有边界的文件窗口（根锁定、基于行、散列）。
• 正则表达式上下文为： 主控程序 rg 返回与以下项匹配的所有正则表达式 before/after 上下文（grep -B/-A/-C)，在硬预算下合并成紧凑的大块。
• 方便别名： 主控程序 grep → rg，以及MCP find → ls （行为相同；只是肌肉记忆名称）。
• 安全文件列表： 主控程序 ls 返回有界文件路径（glob/substring过滤器）。
• 回购入职培训包： 主控程序 repo_onboarding_pack 回报 tree +关键文档(cat)在一个有限的响应中。它在预算紧张的情况下修剪文档前的结构，默认情况下自动刷新索引，并报告 docs_reason 当不包括文档时。
• 一个通话阅读包： 主控程序 read_pack 是每日“项目记忆”的单一入口点，有针对性地读取(file/grep/query)，以及一次电话召回(questions/ask).默认情况下，它返回一个压缩 project_facts 部分+ snippet 有效载荷低于1 max_chars 预算；更丰富的图形/概览输出是可选的。
• 光标分页： 截断后，MCP工具包括 M: 排队 .context 输出，以便代理可以继续而无需猜测。
• 当你要求新鲜时： 语义工具可以通过以下方式报告索引新鲜度 meta.index_state （并重新索引尝试）而不会污染紧环读取；使用 response_mode: "full" 当您需要诊断时。
• 稳定的集成表面： CLI JSON、HTTP、gRPC、MCP——都被视为合约。
• 混合检索： 语义+模糊+融合+配置文件驱动的增强。
• 图形感知上下文： 在需要时附加相关块（调用/导入/测试）。
• 任务包： task_pack 添加 why + next_actions 在...之上 context_pack.
• 有界文本搜索： text_search 是文件系统优先（代理本机 rg 更换），并在预算紧张的情况下保持安全/低噪音；语料库支持仅用于光标兼容性。
• 测量质量： 黄金数据集+MRR/召回率/延迟/字节+A/B比较。
• 离线首款车型： 从清单下载一次，验证sha256，永远不要提交资产。
• 无静默CPU回退： 默认情况下为CUDA；仅在明确允许的情况下才使用CPU。

60秒快速启动

1） 构建和安装

git clone https://github.com/AmirTlinov/context-mcp.git
cd context-mcp

# One command (recommended):
bash scripts/install.sh

# Or manual:
# cargo install --path crates/mcp-server --locked
# cargo install --path crates/cli --locked

可选本地别名（避免 cargo install 迭代期间）：

alias context='./target/release/context'

2） 安装模型（离线）并验证

模型资产一次下载到 ./models/ （gitignored）从 models/manifest.json:

context install-models
context doctor --json

执行政策：

• 默认情况下仅GPU（CUDA）。
• 只有在以下情况下才允许CPU回退 CONTEXT_ALLOW_CPU=1.

3） 索引并请求一个有界的包

cd /path/to/project

context index . --json
context context-pack "index schema version" --path . --max-chars 20000 --json --quiet

注意：在MCP模式下，您通常不会运行 index 手动——索引会自动触发，并在后台逐步保持新鲜。

想要用图扩展进行探索吗？

context context "streaming indexer health" --path . --strategy deep --show-graph --json --quiet

集成

CLI+JSON命令API

一个请求形状；一个响应信封：

context command --json '{"action":"search","payload":{"query":"embedding templates","limit":5,"project":"."}}'

带有保鲜保护和路径过滤器的任务导向包装：

context command --json '{
  "action":"task_pack",
  "options":{"stale_policy":"auto","max_reindex_ms":1500,"include_paths":["src"]},
  "payload":{"intent":"refresh watermark policy","project":".","max_chars":20000}
}'

批处理（一个请求→ 许多行动）：

context command --json '{
  "action":"batch",
  "options":{"stale_policy":"auto","max_reindex_ms":1500},
  "payload":{
    "project":".",
    "max_chars":20000,
    "items":[
      {"id":"idx","action":"index","payload":{"path":"."}},
      {"id":"pack","action":"context_pack","payload":{"query":"stale policy gate","limit":6}}
    ]
  }
}'

笔记：

• items[].id 经过修剪，必须独一无二。
• 项目有效载荷支持 $ref 包装材料： { "$ref": "#/items//data/..." , "$default": ...? } （参见 contracts/command/v1/batch.schema.json).

超文本传输协议

context serve-http --bind 127.0.0.1:7700

# Non-loopback bind requires explicit opt-in + auth:
# export CONTEXT_AUTH_TOKEN='replace-me'
# context serve-http --public --bind 0.0.0.0:7700

• POST /command
• GET /health

gRPC

context serve-grpc --bind 127.0.0.1:50051

# Non-loopback bind requires explicit opt-in + auth:
# export CONTEXT_AUTH_TOKEN='replace-me'
# context serve-grpc --public --bind 0.0.0.0:50051

MCP服务器

cargo install --path crates/mcp-server --locked

自我审计工具清单（不需要MCP客户端）：

context-mcp --print-tools

Codex配置示例(~/.codex/config.toml):

[mcp_servers.context]
command = "context-mcp"
args = []

[mcp_servers.context.env]
CONTEXT_PROFILE = "quality"
# Shared MCP backend is enabled by default (agent-native multi-session UX).
# Set to "0" only if you need an isolated in-process server per session:
# CONTEXT_MCP_SHARED = "0"

# Optional:
# CONTEXT_MODEL_DIR = "/path/to/models"
# CONTEXT_MCP_SOCKET = "/tmp/context-mcp.sock"
# CONTEXT_MCP_LOG = "1" # stderr-only logs (keep off by default for protocol purity)

# Default output is agent-native `.context` plain text (no JSON in chat).
# `structured_content` is intentionally omitted to keep agent context windows clean.

每日项目记忆（一次MCP调用→ 稳定的仓库事实+关键文档）：使用 read_pack:

{ "path": "/path/to/project" }

映射首次入职（一次MCP电话→ 地图+关键文档；使用 response_mode: "full" 用于额外诊断）：使用 repo_onboarding_pack:

{
  "path": "/path/to/project",
  "map_depth": 2,
  "docs_limit": 6,
  "response_mode": "full",
  "max_chars": 6000
}

想要一个MCP工具来替换 cat/sed, rg -C, *和* 语义包？使用 read_pack:

// Daily memory pack (defaults)
{ "path": "/path/to/project" }

// One-call recall (ask multi-part questions in one MCP call)
{
  "path": "/path/to/project",
  "questions": [
    "Where is the HTTP /command route implemented?",
    "How do I run tests in this repo?",
    "re: cargo test", // optional: explicit grep directive (Rust regex syntax)
    "lit: cargo test", // optional: literal grep directive (no regex)
    "fast in:src lit: cursor_fingerprint", // optional: per-question scoping + force fast path
    "deep index:8s k:5 ctx:20 How does auto-index decide the project root? in:crates", // per-question deep mode + knobs
    "deep How does auto-index decide the project root?" // optional: per-question deep mode (semantic + index if needed)
  ],
  "max_chars": 6000
}

// Read a file window (cat)
{
  "path": "/path/to/project",
  "intent": "file",
  "file": "src/lib.rs",
  "start_line": 120,
  "max_lines": 80,
  "max_chars": 2000
}

// Continue without repeating inputs (cursor-only continuation)
{
  "path": "/path/to/project",
  "cursor": ""
}

需要在一个repo中使用N行上下文进行类似grep的读取（没有 rg + sed 循环）？使用 rg:

{
  "path": "/path/to/project",
  "pattern": "stale_policy",
  // Optional: treat `pattern` as a literal string (like `rg -F`)
  // "literal": true,
  "file_pattern": "crates/*/src/*",
  "before": 50,
  "after": 50,
  "max_hunks": 40,
  "max_chars": 2000,
  // Optional: "numbered" (default) prefixes each line with "
: " and marks match lines as "
:* "
  // "format": "numbered"
}

如果输出被截断 .context 文本包括 M: 线。 rg 支持仅光标连续：

{ "path": "/path/to/project", "cursor": "" }

代理友好提示：MCP工具 batch 允许您在一次调用中执行多个工具（一个有界 .context 响应）。 path 是规范的（别名： project).批量 version: 2，项目输入可以通过以下方式依赖于早期的输出 $ref （JSON指针）：

{
  "version": 2,
  "path": "/path/to/project",
  "max_chars": 2000,
  "items": [
    { "id": "hits", "tool": "text_search", "input": { "pattern": "stale_policy", "max_results": 1 } },
    {
      "id": "ctx",
      "tool": "rg",
      "input": {
        "pattern": "stale_policy",
        "file": { "$ref": "#/items/hits/data/matches/0/file" },
        "before": 40,
        "after": 40
      }
    }
  ]
}

当你需要 *精确* 文件区域的内容（无 cat/sed)，使用MCP工具 cat:

{
  "path": "/path/to/project",
  "file": "src/lib.rs",
  "start_line": 120,
  "max_lines": 80,
  "max_chars": 2000
}

如果响应被截断，请继续 cursor:

{
  "path": "/path/to/project",
  "cursor": "",
  "max_chars": 2000
}

当您首先需要文件路径时（无 ls/find/rg --files)，使用 ls:

{
  "path": "/path/to/project",
  "file_pattern": "src/*",
  "limit": 200,
  "max_chars": 2000
}

合同（事实来源）

所有集成界面都是合同优先的，并进行了版本控制：

• 合同/README.md
• contracts/command/v1/ （JSON模式）
• contracts/http/v1/openapi.json （OpenAPI 3.1）
• 原型/ （gRPC）

文档

• docs/README.md （导航中心）
• docs/AGENT_MEMORY.md (read_pack 作为“项目记忆”和每日默认值）
• docs/QUICK_START.md （安装、CLI、服务器、JSON API）
• 用法_示例.md （代理优先工作流）
• docs/ARCHITECTURE.md
• docs/CONTEXT_PACK.md
• docs/COMMAND_RFC.md
• 哲学.md
• 模型/README.md
• bench/README.md

发展

# One command (contracts + structure + fmt + clippy + stub tests + HTTP conformance + stub eval):
bash scripts/validate_quality.sh

# Optional (real embeddings smoke; requires models + CUDA/ORT, or CPU fallback via CONTEXT_ALLOW_CPU=1):
bash scripts/validate_real_embeddings.sh

许可证

麻省理工学院或阿帕奇-2.0

贡献

看 CONTRIBUTING.md.