Docdex MCP


国际贸易融资纠纷仲裁

将您的存储库转变为人类和人工智能可以信任的快速、私密的环境。

Docdex是一个 本地第一索引器和搜索守护进程 用于文档和源代码。它位于原始文件和人工智能助手之间，提供确定性搜索、代码智能和持久内存，而无需将代码上传到云向量存储。

⚡ 为什么选择Docdex？

大多数人工智能工具依赖于“grep”（快速但愚蠢）或托管的RAG（缓慢且需要上传）。Docdex在本地运行，理解代码结构，并为您的AI代理提供持久内存。

______________________________________________________________________

🚀 特性

• 📚 文档索引： 立即对回购文档进行排名和总结。
• 🧠 AST和影响图： 按函数意图搜索并跟踪下游依赖关系（支持Rust、Python、JS/TS、Go、Java、C++等）。
• 💾 回购记忆： 在本地存储项目事实、决策和注释。
• 👤 代理内存： 记住不同存储库中的用户偏好（例如，“使用简洁的要点”）。
• 🗂️ 对话记忆： 导入成绩单，保持唤醒包紧凑，并导出仓库范围的摘要、日记条目和工作内存。
• 🕸️ 时态知识图： 从存档的对话中提取实体、边、情节和面向代码的链接，用于时间线和邻居查询。
• 🧭 唤醒+项目地图上下文： 注入紧凑的唤醒包、配置文件真相和缓存 Project map: 将上下文转换为OpenAI兼容的聊天完成。
• 🔌 MCP本地： 自动配置Claude Desktop、Cursor和Windsurf等工具。
• 🌐 网络丰富： 可选择使用本地LLM过滤的网络搜索（通过Ollama）。

______________________________________________________________________

📦 设置并忘记安装

安装一次，将代理指向Docdex，它就会在后台继续工作。

1.通过npm安装（推荐）

需要Node.js>=18。这将为您的操作系统（macOS、Linux、Windows）下载正确的二进制文件。

npm i -g docdex

\[！警告\] Windows要求： Docdex使用MSVC运行时。安装 微软Visual C++可再发行版2015-2022（x64） 跑步前 docdex/docdexd. - 翼： winget install --id Microsoft.VCRedist.2015+.x64 - 手册：下载 vc_redist.x64.exe 来自微软：https://aka.ms/vs/17/release/vc_redist.x64.exe - 如果 docdexd 出口与 0xC0000135，缺少运行时。

2.自动配置

如果您安装了以下任何客户端，Docdex会自动将其配置为使用本地MCP端点（守护进程HTTP/SSE）：

克劳德桌面、光标、风帆、Cline、Roo代码、继续、VS代码、PearAI、Void、Zed、Codex。

*注意：安装后重新启动AI客户端。*

______________________________________________________________________

🛠️ 使用工作流程

1.为存储库建立索引

运行一次此命令以构建索引和图形数据。

docdexd index --repo /path/to/my-project

2.启动守护进程

启动共享服务器。这处理HTTP请求和MCP连接。

docdex start
# or: docdexd daemon --host 127.0.0.1 --port 28491

3.提问（CLI）

您可以直接从终端聊天。

docdexd chat --repo /path/to/my-project --query "how does auth work?"

______________________________________________________________________

🔌 模型上下文协议（MCP）

Docdex旨在成为您的AI代理的“大脑”。它公开了代理连接到的MCP端点。

建筑

flowchart LR
  Repo[Repo on disk] --> Indexer[Docdex Indexer]
  Indexer --> Daemon[Docdex Daemon]
  Daemon -->|HTTP + SSE| MCPClient[MCP Client]
  MCPClient --> Host[AI Agent / Editor]

使用守护进程HTTP/SSE端点。对于沙盒客户端，Docdex还可以通过本地IPC为MCP提供服务 （Unix套接字或Windows命名管道），而HTTP/SSE仍然是大多数MCP客户端的默认设置。

手动配置

如果您需要手动配置客户端：

JSON（克劳德/光标/继续）：

{
  "mcpServers": {
    "docdex": {
      "url": "http://127.0.0.1:28491/v1/mcp/sse"
    }
  }
}

Claude代码（CLI）JSON(~/.claude.json 或项目 .mcp.json):

{
  "mcpServers": {
    "docdex": {
      "type": "http",
      "url": "http://127.0.0.1:28491/v1/mcp"
    }
  }
}

TOML（食品法典委员会）：

[mcp_servers.docdex]
url = "http://127.0.0.1:28491/v1/mcp"
tool_timeout_sec = 300
startup_timeout_sec = 300

______________________________________________________________________

🤖 能力和示例

1.AST和影响分析

不要只找到字符串“addressGenerator”；找到 定义 以及它的影响。

# Find definition
curl "http://127.0.0.1:28491/v1/ast?name=addressGenerator&pathPrefix=src"

# Track downstream impact (what breaks if I change this?)
curl "http://127.0.0.1:28491/v1/graph/impact?file=src/app.ts&maxDepth=3"

2.存储系统

Docdex允许您存储检索有助于以后回忆的“事实”。

回购内存（特定于项目）：

# Teach the repo a fact
docdexd memory-store --repo . --text "Payments retry up to 3 times with backoff."

# Recall it later
docdexd memory-recall --repo . --query "payments retry policy"

代理内存（用户首选项）：

# Set a style preference
docdexd profile add --agent-id "default" --category style --content "Use concise bullet points."

3.对话记忆

默认情况下，会话内存是repo作用域，并且是可选的。无回购会话必须使用显式的对话命名空间，这样它们就永远不会默默地重用回购存档。该子系统将成绩单导入，存储情节摘要和工作记忆，将日记条目和时间KG事实导出到 knowledge.db，并在严格的唤醒预算下进行召回。

CLI归档、日记和钩子命令是HTTP支持的包装器，因此开始 docdex start 或 docdexd daemon 第一。

# Archive and inspect transcripts
docdexd conversations import --repo . ./session.txt --format plain_text --agent-id codex
docdexd conversations list --repo . --agent-id codex
docdexd conversations search --repo . "timeline_index"
docdexd conversations read --repo . 

# Import into an explicit global conversation namespace instead of a repo archive
docdexd conversations import --conversation-namespace shared-team ./session.txt --format plain_text --agent-id codex
docdexd conversations search --conversation-namespace shared-team "timeline_index"

# Keep agent diary notes alongside imported sessions
docdexd diary write --repo . --agent-id codex "Wake-up rollout validated against knowledge.db timeline output."
docdexd diary read --repo . --agent-id codex

# Trigger durable summarization from an external transcript
docdexd hook conversation --repo . \
  --action session_close_summarization \
  --source codex \
  --agent-id codex \
  --transcript ./session.txt \
  --format plain_text \
  --wait-for-processing

# Build a compact wake-up bundle over recent context
curl -X POST http://127.0.0.1:28491/v1/wakeup \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"codex","query":"timeline_index","max_tokens":96}'

# Address the same archive over HTTP without repo_id
curl -X POST http://127.0.0.1:28491/v1/wakeup \
  -H "Content-Type: application/json" \
  -H "x-docdex-conversation-namespace: shared-team" \
  -d '{"agent_id":"codex","query":"timeline_index","max_tokens":96}'

# Explore derived repo-scoped knowledge facts and provenance
curl "http://127.0.0.1:28491/v1/kg/query?q=knowledge.db&limit=10"
curl "http://127.0.0.1:28491/v1/kg/search/nodes?q=knowledge&limit=10"
curl "http://127.0.0.1:28491/v1/kg/neighborhood?entity=knowledge.db&limit=10"
curl "http://127.0.0.1:28491/v1/kg/timeline?entity=knowledge.db&limit=10"

# Chat with wake-up + project-map context and inspect reasoning trace metadata
curl -X POST http://127.0.0.1:28491/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fake-model",
    "messages": [{"role": "user", "content": "What changed around knowledge.db?"}],
    "docdex": {
      "agent_id": "codex",
      "limit": 6,
      "include_libs": true,
      "dag_session_id": "session-123"
    }
  }'

4.当地LLM（Ollama）

Docdex使用Ollama进行嵌入和可选的本地聊天。

• 设置： 跑 docdex setup 对于交互式向导。
• 手册： 确保 nomic-embed-text 被拉到Ollama(ollama pull nomic-embed-text).
• 自定义URL:

DOCDEX_OLLAMA_BASE_URL=http://127.0.0.1:11434 docdex start --host 127.0.0.1 --port 28491

______________________________________________________________________

⚙️ 配置和HTTP API

Docdex作为本地守护进程运行，服务于：

• CLI命令： docdexd chat
• HTTP API： /search, /v1/capabilities, /v1/search/rerank, /v1/search/batch, /v1/chat/completions, /v1/ast, /v1/graph/impact, /v1/conversations/*, /v1/diary/*, /v1/hooks/conversation, /v1/wakeup, /v1/kg/*
• MCP端点： /v1/mcp 和 /v1/mcp/sse
• 能力协商工具： docdex_capabilities, docdex_rerank, docdex_batch_search, docdex_conversation_*, docdex_diary_*, docdex_conversation_hook, docdex_wakeup, docdex_kg_*

多回购设置

运行一个守护进程，并根据需要挂载其他存储库。

docdex start --port 28491

# Mount repos and capture repo_id values
curl -X POST "http://127.0.0.1:28491/v1/initialize" \
  -H "Content-Type: application/json" \
  -d '{"rootUri":"file:///path/to/repo-a"}'

curl -X POST "http://127.0.0.1:28491/v1/initialize" \
  -H "Content-Type: application/json" \
  -d '{"rootUri":"file:///path/to/repo-b"}'

笔记：

• 当挂载多个仓库时（或者守护进程在没有默认仓库的情况下启动），包括 x-docdex-repo-id: HTTP请求。
• MCP会话绑定到中提供的仓库 initialize.rootUri 并自动重用该仓库。

安全

• 安全模式： 默认情况下，Docdex对非环回绑定强制执行TLS。
• 环回： 127.0.0.1 本地代理可以在没有TLS的情况下访问。
• 要暴露于网络（请谨慎使用），请使用 --expose 和 --auth-token.

______________________________________________________________________

📚 了解更多

• 详细用法： docs/usage.md
• API参考： docs/http_api.md
• MCP规格： docs/mcp/errors.md