文档-mcp

Name: 文档-mcp
Author: bsreeram08

作者：bsreeram085 星标更新：2025-10-27

安装使用来源：spider==github.com

项目介绍

CogniDocs - 文档MCP服务器 - 灵活后端配置

CogniDocs是一款基于模型上下文协议（MCP）的服务器，它为AI助手提供了搜索和查询文档的能力。现在支持灵活的后端配置以满足不同的隐私和基础设施需求。

🆕 新功能 - 灵活的后端架构

此版本引入了一个完整的后端抽象层，允许您选择您偏好的技术堆栈：

存储选项

ChromaDB - 开源向量数据库

嵌入选项

Xenova/Transformers - 本地、注重隐私的嵌入
Transformers.js (@huggingface/transformers) - 官方HF JS运行时（默认使用WASM）

提供商注册和无提供商依赖的配置（新）

我们现在使用插件式的提供商注册表，并自动注册。配置不再在模式中引用特定的提供商；而是指定：

# 存储
STORAGE_NAME=chroma
STORAGE_OPTIONS={"url":"http://localhost:8000"}

# 嵌入
EMBEDDINGS_NAME=xenova
EMBEDDINGS_OPTIONS={"model":"Xenova/all-MiniLM-L6-v2","maxBatchSize":50}

# 替代方案（Transformers.js）
# EMBEDDINGS_NAME=transformersjs
# EMBEDDINGS_OPTIONS={"model":"Xenova/all-MiniLM-L6-v2","device":"wasm","pooling":"mean","normalize":true,"maxBatchSize":50}

注意事项：

提供商通过app/*/providers/index.ts副作用导入进行自我注册（例如，app/embeddings/providers/index.ts，app/storage/providers/index.ts，app/chunking/providers/index.ts）。
添加一个提供商就像添加一个调用register*Provider()的新文件一样简单。
旧变量如STORAGE_PROVIDER，EMBEDDING_PROVIDER，CHROMA_URL，XENOVA_MODEL在解析时仍然支持，但已弃用。

分块更新

默认分块器是LangChain，采用递归策略。
推荐默认设置：chunkSize=3000，chunkOverlap=150。
通过CHUNKING_NAME=langchain和CHUNKING_OPTIONS={"strategy":"recursive","chunkSize":3000,"chunkOverlap":150}进行配置。
LangChain提供商中的其他策略：
- intelligent：内容类型感知分割（根据代码、markdown、html等调整分隔符/大小）。
- semantic：初始分割+当嵌入余弦相似度超过阈值时相邻合并。
Chonkie提供商将输出标准化为字符串，因此Chunk.text始终是一个字符串。

🧭 代理文档处理（可选）（待办事项）

代理引导的分块和注释可以通过将分块对齐到主题边界并丰富它们的元数据（主题标签、章节标题、代码语言、实体、摘要和质量评分）来显著提高大型多主题文档的搜索质量。这设计为一个可选的、无提供商依赖的摄入阶段。

了解更多：参见docs/agentic-processing.md。

🏗️ 架构

---
config:
  layout: dagre
  theme: redux
  look: neo
---
flowchart LR
 subgraph subGraph0["存储提供商"]
        chroma["ChromaDB"]
        storage["存储层"]
  end
 subgraph subGraph1["嵌入提供商"]
        xenova["Xenova"]
        embeddings["嵌入层"]
  end
 subgraph subGraph2["分块提供商"]
        langchain["LangChain (默认)"]
        chunking["分块层"]
        chonkie["Chonkie"]
        builtin["内置"]
  end
    client["MCP客户端 (Claude)"] --- upload["HTTP上传服务器"]
    web["Web UI (可选)"] --- upload
    upload --> abstractions["提供商抽象\n(存储 / 嵌入 / 分块)"]
    abstractions --> storage & embeddings & chunking
    storage --> chroma
    embeddings --> xenova
    chunking --> langchain & chonkie & builtin

🚀 快速开始

安装与设置

注重隐私的设置（仅本地）

# 克隆并安装
git clone <仓库>
cd cogni-docs
bun install

# 配置本地处理
cp .env.example .env
# 编辑.env以包含无提供商依赖的配置：
STORAGE_NAME=chroma
STORAGE_OPTIONS={"url":"http://localhost:8000"}
EMBEDDINGS_NAME=xenova
EMBEDDINGS_OPTIONS={"model":"Xenova/all-MiniLM-L6-v2","maxBatchSize":50}

# 分块（默认：LangChain递归）
CHUNKING_NAME=langchain
CHUNKING_OPTIONS={"strategy":"recursive","chunkSize":3000,"chunkOverlap":150}

# 启动服务器
# 启动服务器（上传 + MCP在同一端口）
bun run upload-server:prod  # 默认端口：3001（设置HTTP_PORT）。使用:dev以启用监视模式

混合设置（ChromaDB + 本地嵌入）

# 启动ChromaDB
docker run -p 8000:8000 chromadb/chroma

# 配置应用
STORAGE_NAME=chroma
STORAGE_OPTIONS={"url":"http://localhost:8000"}
EMBEDDINGS_NAME=xenova
EMBEDDINGS_OPTIONS={"model":"Xenova/all-MiniLM-L6-v2"}

# 启动应用
bun run upload-server:prod

📋 配置选项

环境变量

变量	类型	描述
`HTTP_PORT`	数字	上传服务器端口（示例默认：3001，配置默认：8787）
`STORAGE_NAME`	字符串	存储提供商名称（例如，`chroma`）
`STORAGE_OPTIONS`	JSON	提供商特定选项作为JSON（例如，`{ "url": "http://localhost:8000" }`或`{ "projectId": "..." }`）
`EMBEDDINGS_NAME`	字符串	嵌入提供商名称（例如，`xenova`）
`EMBEDDINGS_OPTIONS`	JSON	提供商特定选项作为JSON（例如，`{ "model": "Xenova/all-MiniLM-L6-v2" }`）
`CHUNKING_NAME`	字符串	分块提供商名称：`langchain`（默认），`chonkie`，或`builtin`
`CHUNKING_OPTIONS`	JSON	提供商特定分块选项作为JSON（例如，`{ "strategy": "recursive", "chunkSize": 3000, "chunkOverlap": 150 }`）
`CHUNK_SIZE`	数字	向后兼容：目标分块大小（默认：3000）
`CHUNK_OVERLAP`	数字	向后兼容：分块之间的重叠（默认：150）
`MAX_CHUNK_SIZE`	数字	向后兼容：分块大小的硬上限（默认：5000）

查看.env.example以获取完整的配置选项。

分块策略（LangChain）

recursive（默认）：

CHUNKING_NAME=langchain
CHUNKING_OPTIONS={"strategy":"recursive","chunkSize":3000,"chunkOverlap":150}

intelligent（内容类型感知：代码/markdown/html会调整分隔符及大小）：

CHUNKING_NAME=langchain
CHUNKING_OPTIONS={"strategy":"intelligent","chunkSize":3000,"chunkOverlap":150,"contentTypeAware":true}

semantic（通过嵌入相似性相邻合并）：

CHUNKING_NAME=langchain
CHUNKING_OPTIONS={
  "strategy":"semantic",
  "chunkSize":3000,
  "chunkOverlap":150,
  "contentTypeAware":true,
  "semanticSimilarityThreshold":0.9,
  "semanticMaxMergeChars":6000,
  "semanticBatchSize":64
}

注意事项：

根据语料库调整semanticSimilarityThreshold（通常0.85–0.92）。
如果嵌入不可用，提供商应退回到初始分割（不合并）。

已弃用（仍为向后兼容而解析）：STORAGE_PROVIDER，EMBEDDING_PROVIDER，CHROMA_URL，XENOVA_MODEL，MAX_BATCH_SIZE，UPLOAD_SERVER_PORT，UPLOAD_SERVER_HOST。

🔧 技术堆栈比较

特征	ChromaDB + Xenova
隐私	✅ 自托管
性能	✅ 良好
可扩展性	✅ 高
设置复杂度	⚠️ 中等
成本	💰 基础设施
离线支持	⚠️ 部分

🎯 使用场景

企业/生产

→ ChromaDB + Xenova

自动扩展
企业级安全
管理基础设施

注重隐私

→ ChromaDB + Xenova

无外部云依赖
完全的数据控制
在隔离环境中工作

开发/研究

→ ChromaDB + Xenova

易于实验
性能良好
部署灵活

📁 项目结构

app/
├── index.ts                     # 启动HTTP上传 + MCP服务器
├── config/
│   └── app-config.ts            # Zod验证，无提供商依赖的配置
├── chunking/                    # 分块接口、工厂和提供商
│   ├── chunker-interface.ts
│   ├── chunking-factory.ts
│   └── providers/               # 提供商：langchain（默认）、chonkie、内置
├── storage/
│   ├── storage-interface.ts     # 存储接口
│   ├── chroma-storage.ts        # ChromaDB实现
│   └── storage-factory.ts       # 提供商注册表 + 工厂
├── embeddings/
│   ├── embedding-interface.ts   # 嵌入接口
│   ├── embedding-factory.ts     # 提供商注册表 + 工厂
│   └── providers/               # 嵌入提供商（例如，Xenova）
├── server/
│   └── mcp-server.ts            # MCP工具 + SSE传输（/sse，/messages）
├── ingest/
│   └── chunker.ts               # 摄入入口点；使用分块服务
└── parsers/
    ├── pdf.ts                   # PDF解析器
    ├── html.ts                  # HTML解析器
    └── text.ts                  # 纯文本解析器

🔌 API端点

上传服务器（端口3001）

GET /health - 服务健康检查，包括提供商状态
GET /sets - 列出文档集
POST /sets - 创建文档集
GET /sets/:setId - 获取特定集合
GET /sets/:setId/documents - 列出集合中的文档
POST /sets/:setId/upload - 上传文档
DELETE /sets/:setId/documents/:docId - 删除文档

MCP服务器（HTTP SSE）

传输：GET /sse（事件流），POST /messages（JSON消息）
工具：
- list_documentation_sets - 列出可用的集合
- get_documentation_set - 获取特定集合的详细信息
- search_documentation - 在集合内进行向量搜索
- agentic_search - 提取式、基于上下文的答案

🛠️ 开发

# 安装依赖
bun install

# 开启文件监视的开发
bun run upload-server:dev  # 启动带有热重载的上传+MCP服务器
bun run web:dev            # 启动Web UI开发服务器

# 类型检查
bun run typecheck

# 为生产构建
bun run web:build

🔍 健康监控

检查服务状态：

curl http://localhost:3001/health

响应包括：

整体服务健康状况
存储提供商状态
嵌入提供商状态
系统运行时间

🤝 贡献

灵活的后端架构使得添加新的提供商变得容易：

存储提供商：实现StorageService接口
嵌入提供商：实现EmbeddingService接口
更新工厂：添加到相应的工厂文件
配置：添加选项到配置模式

📄 许可证

MIT许可证 - 查看LICENSE文件以获取详情。

一款提供AI助手搜索和查询文档能力的MCP服务器，使用本地优先、无提供商依赖的后端。

架构

该项目实现了双服务器架构：

HTTP上传服务器 - 用于文档摄入和管理
MCP服务器 - 用于AI助手查询文档

关键特性

多格式解析：PDF、HTML和纯文本文档
代理搜索：通过MCP工具从您的文档中提取基于上下文的答案
多租户：多个文档集，具有独立的搜索
现代堆栈：Bun运行时，TypeScript，Elysia框架

快速开始

先决条件

安装了Bun运行时
Docker（可选）用于ChromaDB

设置

克隆并安装依赖项：

bun install

配置环境：

cp .env.example .env
# 编辑.env以包含您的无提供商依赖设置

启动上传服务器：

bun run upload-server

在另一个终端中启动MCP服务器：

bun run mcp-server

使用

1. 上传文档

创建一个文档集并上传文件：

# 创建一个文档集
curl -X POST http://localhost:3001/sets \
  -H "Content-Type: application/json" \
  -d '{"name": "我的API文档", "description": "REST API文档"}'

# 上传文档（PDF、HTML、TXT）
curl -X POST http://localhost:3001/sets/{SET_ID}/upload \
  -F "files=@文档.pdf" \
  -F "files=@API指南.html"

2. 通过MCP查询

MCP服务器暴露四个工具：

list_documentation_sets - 列出所有可用的文档集
get_documentation_set - 获取特定集合的详细信息
search_documentation - 在集合内进行基本向量搜索
agentic_search - 从您的文档中提取基于上下文的答案

3. 代理搜索示例

// 在Claude或其他兼容MCP的AI助手中
await mcp.callTool("agentic_search", {
  setId: "您的集合ID",
  query: "如何认证API请求？",
  limit: 10,
});

配置

环境变量

# 核心
HTTP_PORT=3001

# 无提供商依赖
STORAGE_NAME=chroma
STORAGE_OPTIONS={"url":"http://localhost:8000"}
EMBEDDINGS_NAME=xenova
EMBEDDINGS_OPTIONS={"model":"Xenova/all-MiniLM-L6-v2","maxBatchSize":50}

# 分块
CHUNKING_NAME=langchain
CHUNKING_OPTIONS={"strategy":"recursive","chunkSize":3000,"chunkOverlap":150}
CHUNK_SIZE=3000
CHUNK_OVERLAP=150
MAX_CHUNK_SIZE=5000

开发

脚本

bun run upload-server:dev  # 热重载上传+MCP服务器
bun run upload-server:prod # 生产上传+MCP服务器
bun run web:dev            # Web UI开发
bun run typecheck          # 类型检查

添加新的文档类型

在app/parsers/中创建解析器
注册/路由现有的解析器旁边的MIME类型
确保在app/ingest/chunker.ts中的分块策略适合新的类型

架构决策

为什么选择Bun？

性能：快速启动和运行时
原生TypeScript：无需编译步骤
现代工具链：内置测试、捆绑和包管理

故障排除

SSE传输断开连接

为了稳定性，偏好使用bun run upload-server:prod（非监视模式）。
确保您的MCP客户端使用GET /sse（而非POST）和POST /messages。
如果IDE会话过期，请重新加载MCP客户端以重新握手。

ChromaDB连接问题

验证Chroma正在运行且STORAGE_OPTIONS={"url":"http://localhost:8000"}。
检查GET /health以获取存储状态；如果Chroma宕机，请重启。