使用说明

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

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

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

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

存储选项

ChromaDB -开源矢量数据库

嵌入选项

Xenova/变压器 -本地、注重隐私的嵌入
Transformers.js（@huggingface/transfers） -官方HF JS运行时（服务器上默认为WASM）

提供程序注册表和提供程序无关配置（新）

我们现在使用具有自动注册功能的插件式提供者注册表。配置不再引用架构中的特定提供程序；相反，您可以指定：

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

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

# Alternative (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 它总是一个字符串。

🧭 代理文档处理（摄取，可选）（TODO）

代理引导的组块和注释可以通过将组块与主题边界对齐并用元数据（主题标签、节标题、代码语言、实体、摘要和质量分数）丰富它们，大大提高大型多主题文档的搜索质量。这被设计为在摄入时是一个可选的、与提供者无关的阶段。

了解更多：请参阅 docs/agentic-processing.md.

🏗️ 建筑

---
config:
  layout: dagre
  theme: redux
  look: neo
---
flowchart LR
 subgraph subGraph0["Storage Providers"]
        chroma["ChromaDB"]
        storage["Storage Layer"]
  end
 subgraph subGraph1["Embedding Providers"]
        xenova["Xenova"]
        embeddings["Embedding Layer"]
  end
 subgraph subGraph2["Chunking Providers"]
        langchain["LangChain (default)"]
        chunking["Chunking Layer"]
        chonkie["Chonkie"]
        builtin["Builtin"]
  end
    client["MCP Client (Claude)"] --- upload["HTTP Upload Server"]
    web["Web UI (Optional)"] --- upload
    upload --> abstractions["Provider Abstractions\n(Storage / Embeddings / Chunking)"]
    abstractions --> storage & embeddings & chunking
    storage --> chroma
    embeddings --> xenova
    chunking --> langchain & chonkie & builtin

🚀 快速开始

安装和设置

以隐私为中心的设置（仅限本地）

# Clone and install
git clone <repository>
cd cogni-docs
bun install

# Configure for local processing
cp .env.example .env
# Edit .env with provider-agnostic config:
STORAGE_NAME=chroma
STORAGE_OPTIONS={"url":"http://localhost:8000"}
EMBEDDINGS_NAME=xenova
EMBEDDINGS_OPTIONS={"model":"Xenova/all-MiniLM-L6-v2","maxBatchSize":50}

# Chunking (default: LangChain recursive)
CHUNKING_NAME=langchain
CHUNKING_OPTIONS={"strategy":"recursive","chunkSize":3000,"chunkOverlap":150}

# Start servers
# Start server (Upload + MCP on the same port)
bun run upload-server:prod  # Default :3001 (set HTTP_PORT). Use :dev for watch mode

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

# Start ChromaDB
docker run -p 8000:8000 chromadb/chroma

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

# Start app
bun run upload-server:prod

📋 配置选项

环境变量

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

看 .env.example 了解完整的配置选项。

分块策略（LangChain）

recursive （默认）：

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

intelligent （内容类型感知：code/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                     # Starts HTTP Upload + MCP server
├── config/
│   └── app-config.ts            # Zod-validated, provider-agnostic config
├── chunking/                    # Chunking interface, factory, and providers
│   ├── chunker-interface.ts
│   ├── chunking-factory.ts
│   └── providers/               # Providers: langchain (default), chonkie, builtin
├── storage/
│   ├── storage-interface.ts     # Storage interface
│   ├── chroma-storage.ts        # ChromaDB implementation
│   └── storage-factory.ts       # Provider registry + factory
├── embeddings/
│   ├── embedding-interface.ts   # Embeddings interface
│   ├── embedding-factory.ts     # Provider registry + factory
│   └── providers/               # Embedding providers (e.g., Xenova)
├── server/
│   └── mcp-server.ts            # MCP tools + SSE transport (/sse, /messages)
├── ingest/
│   └── chunker.ts               # Ingestion entrypoint; uses chunking service
└── parsers/
    ├── pdf.ts                   # PDF parser
    ├── html.ts                  # HTML parser
    └── text.ts                  # Plain text parser

🔌 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 -基于上下文的摘录式答案

🛠️ 发展

# Install dependencies
bun install

# Development with file watching
bun run upload-server:dev  # Upload+MCP server with hot reload
bun run web:dev            # Web UI development server

# Type checking
bun run typecheck

# Build for production
bun run web:build

🔍 健康监测

检查服务状态：

curl http://localhost:3001/health

答复包括：

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

🤝 贡献

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

存储提供程序：实施 StorageService 接口
嵌入提供者：实施 EmbeddingService 接口
更新工厂：添加到相应的工厂文件中
配置：向配置架构添加选项

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件。

一种模型上下文协议（MCP）服务器，为AI助手提供使用本地优先、与提供商无关的后端搜索和查询文档的能力。

建筑

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

HTTP上传服务器 -用于文件接收和管理
MCP服务器 -让AI助手查询文档

主要特点

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

快速开始

先决条件

Bun运行时已安装
ChromaDB的Docker（可选）

设置

克隆和安装依赖关系：

bun install

配置环境：

cp .env.example .env
# Edit .env with your provider-agnostic settings

启动上传服务器：

bun run upload-server

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

bun run mcp-server

用法

1.上传文件

创建文档集并上传文件：

# Create a documentation set
curl -X POST http://localhost:3001/sets \
  -H "Content-Type: application/json" \
  -d '{"name": "My API Docs", "description": "REST API documentation"}'

# Upload documents (PDF, HTML, TXT)
curl -X POST http://localhost:3001/sets/{SET_ID}/upload \
  -F "files=@documentation.pdf" \
  -F "files=@api-guide.html"

2.通过MCP查询

MCP服务器公开了四个工具：

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

3.代理搜索示例

// In Claude or another MCP-compatible AI assistant
await mcp.callTool("agentic_search", {
  setId: "your-set-id",
  query: "How do I authenticate API requests?",
  limit: 10,
});

配置

环境变量

# Core
HTTP_PORT=3001

# Provider-agnostic
STORAGE_NAME=chroma
STORAGE_OPTIONS={"url":"http://localhost:8000"}
EMBEDDINGS_NAME=xenova
EMBEDDINGS_OPTIONS={"model":"Xenova/all-MiniLM-L6-v2","maxBatchSize":50}

# Chunking
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  # Hot reload Upload+MCP server
bun run upload-server:prod # Production Upload+MCP server
bun run web:dev            # Web UI dev
bun run typecheck          # Type checking

添加新文档类型

在中创建解析器 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。

嵌入模型设置

Xenova/Transformers.js模型在首次运行时下载；如果需要，允许网络访问一次。
调整 EMBEDDINGS_OPTIONS （例如。， maxBatchSize)如果你看到内存警告。
如果更改模型/提供者，嵌入尺寸可能会有所不同。使用新鲜的集合或重新填充，以避免混合尺寸。

未来的增强功能

[]支持更多文档格式（DOCX、Markdown）
[]文档元数据搜索和过滤
[]批量上传改进
[]矢量搜索优化
[]上传服务器的身份验证
[]指标和监测

贡献

此项目遵循用户的编码指南：

具有正确类型的TypeScript
函数式编程模式
模块化架构
全面的错误处理

许可证

麻省理工学院

要安装依赖项，请执行以下操作：

bun install

要运行：

bun run upload-server:prod

此项目是使用创建的 bun init 在bun v1.2.20中。包子是一个快速的一体化JavaScript运行时。

使用说明

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

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

存储选项

嵌入选项

提供程序注册表和提供程序无关配置（新）

分块更新

🧭 代理文档处理（摄取，可选）（TODO）

🏗️ 建筑

🚀 快速开始

以隐私为中心的设置（仅限本地）

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

📋 配置选项

环境变量

分块策略（LangChain）

🔧 技术栈比较

🎯 用例

企业/生产

隐私敏感

开发/研究

📁 项目结构

🔌 API终点

上传服务器（端口3001）

MCP服务器（HTTP SSE）

🛠️ 发展

🔍 健康监测

🤝 贡献

📄 许可证

建筑

主要特点

快速开始

先决条件

设置

用法

1.上传文件

2.通过MCP查询

3.代理搜索示例

配置

环境变量

发展

脚本

添加新文档类型

体系结构决策

为什么是Bun？

故障排除

SSE传输断开连接

ChromaDB连接

嵌入模型设置

未来的增强功能

贡献

许可证

相关 MCP

DuckDuckGo 搜索 MCP 服务器

图表生成MCP服务器

Qdrant向量搜索MCP服务器

AI开发助手

必应中文搜索MCP服务器

开发者辅助工具