MCP Md Index

mcp-md指数

🏠 当地人 背景7 用于您自己的markdown文档

⚠️ 概念验证 –这个项目是一个POC，在生产使用之前需要更多的测试。

一个开源MCP服务器，在本地为您的markdown文档建立索引，缓存它，并为AI代理查询返回令牌约束的摘录。

运作原理

1. 首次查询加载和索引 完整文件（例如。， docs/nats.md)
2. 将其缓存在本地 在 .mcp-cache/ 用于快速后续访问
3. 后续查询 检索根据您的提示定制的小型、源链接、令牌约束的摘录（例如“消费者-500个令牌”）
4. 不重新加载完整文档 初始索引后需要

特性

• 📄 智能分块 –按标题拆分标记，每个块可配置最小/最大行数
• 🔍 BM25评分 –使用基于TF-IDF的排名来查找最相关的摘录
• 🧠 混合搜索 –（实验）将BM25与Ollama嵌入相结合，以实现语义相似性
• 🔗 源链接 –每个摘录都包括 path#L-L 便于导航
• 📦 持久缓存 –索引在服务器重启后仍然有效（文件哈希验证）
• ⚡ 令牌有界 –返回符合指定令牌限制的摘录（默认值：500）
• 🌐 网站支持 -获取并索引任何URL作为markdown（HTML→Markdown转换）

安装

go install github.com/bad33ndj3/mcp-md-index@latest

或者克隆并构建：

git clone https://github.com/bad33ndj3/mcp-md-index.git
cd mcp-md-index
go build -o mcp-md-index .

用法

使用Claude、Cursor或其他MCP客户端进行配置

添加到您的MCP配置中（例如。， ~/.cursor/mcp.json):

{
  "mcpServers": {
    "mcp-md-index": {
      "command": "mcp-md-index"
    }
  }
}

或者如果不在，则使用绝对路径 $PATH:

{
  "mcpServers": {
    "mcp-md-index": {
      "command": "/path/to/mcp-md-index"
    }
  }
}

工具

docs_load

加载并索引一个markdown文件。在本地缓存它，以便快速进行后续查询。

参数：

例子：

{
  "path": "docs/nats.md"
}

答复：

Indexed and cached.

doc_id: a1b2c3d4e5f67890
path: docs/nats.md
chunks: 42
cache: .mcp-md-index-cache/a1b2c3d4e5f67890.index.json

docs_query

查询索引文档。如果没有 doc_id 或 path 提供，搜索 所有加载的文档.

参数：

如果两者都有 doc_id 和 path 省略，搜索范围 全部 加载的文档。

例子：

{
  "path": "docs/nats.md",
  "prompt": "consumer configuration",
  "max_tokens": 500
}

答复：

### Consumer Configuration
Source: docs/nats.md#L142-L168

A consumer is a stateful view of a stream...

--------------------------------

### Durable Consumers
Source: docs/nats.md#L170-L195

Durable consumers persist their state...

docs_load_glob

加载多个与glob模式匹配的markdown文件。

参数：

例子：

{
  "pattern": "docs/**/*.md"
}

site_loads

获取多个网站URL，将HTML转换为markdown，并缓存它们。

参数：

例子：

{
  "urls": ["https://docs.nats.io/jetstream", "https://pkg.go.dev/example"]
}

答复：

Loaded 2 sites (1 from cache, 0 failed)

- https://docs.nats.io/jetstream (chunks: 28)
- https://pkg.go.dev/example (chunks: 15)

docs_list

列出当前缓存的所有文档。

参数： 无

答复：

Loaded documents: 2

- doc_id: a1b2c3d4e5f67890
  path: /path/to/.mcp-md-index-cache/a1b2c3d4e5f67890.md
  chunks: 28
  indexed_at: 2024-01-15T10:30:00Z

- doc_id: def456789abcdef0
  path: docs/nats.md
  chunks: 42
  indexed_at: 2024-01-15T09:00:00Z

缓存的工作原理

• 缓存位置： .mcp-cache/ 在当前工作目录中（可配置为 -cache-dir 旗帜）
• 缓存密钥： 绝对文件路径的SHA256哈希值（前16个字符）
• 无效： 文件内容哈希值更改时自动
• 版本控制： 缓存包含一个版本号；不兼容的缓存被拒绝

工作流示例

You: Load the NATS documentation
Agent: Uses docs_load with path "docs/nats.md"
       → Indexes 42 chunks, caches to disk

You: How do I configure a consumer?
Agent: Uses docs_query with prompt "consumer configuration"
       → Returns ~500 tokens of relevant excerpts with source links

You: What about push consumers?
Agent: Uses docs_query with prompt "push consumers"
       → Instant response from cached index (no re-read of file)

You: Load the JetStream docs from the website
Agent: Uses site_load with url "https://docs.nats.io/jetstream"
       → Fetches, converts to markdown, indexes and caches

You: What docs do you have loaded?
Agent: Uses docs_list
       → Shows all cached documents with doc_ids

代理说明

添加到您的 AGENTS.md:

For documentation lookup: use `docs_list` first, then `docs_query` (searches all docs if no path given), or `docs_load_glob`/`site_loads` to load new docs.

实验性：Olama植入物

使用向量嵌入启用语义搜索 奥拉玛。这允许 docs_query 即使确切的关键字不匹配，也能找到相关内容。

设置

1. 安装Ollama 并拉取嵌入模型：

   ollama pull nomic-embed-text

1. 带着实验旗帜奔跑:

   mcp-md-index -experimental-embeddings

建筑

• 非阻塞: docs_load 立即返回；嵌入在后台生成。
• 混合评分：一旦嵌入准备就绪，搜索结果将使用BM25（30%）和余弦相似度（70%）的组合进行排名。
• 坚韧的：如果Ollama无法访问或嵌入尚未准备好，则自动回退到纯BM25。

配置标志

许可证

麻省理工学院