GoodDocs MCP服务器
开源 MCP（模型上下文协议）服务器，用于处理文档。允许异步索引、在PostgreSQL中存储、语义搜索和基于AI的文档分析。
这是一个根据MIT许可证授权的开源项目。欢迎投稿！
✨ 特性
- 🔄 异步索引 -使用任务队列系统和进度跟踪进行异步索引
- 📊 PostgreSQL存储 -用于向量嵌入的pgvector持久存储
- 🔍 语义搜索 -支持多个嵌入提供者的基于向量的语义搜索
- 🤖 AI分析 -使用AI对概念进行详细分析
- 📚 学习援助 -帮助学习不同复杂程度的解释
- 🌐 REST API -交互式REST API与Swagger文档
- 🔌 MCP协议 -为AI客户端提供完整的MCP协议支持
🚀 快速开始
选项1:Docker（推荐）
在Docker中运行所有东西——后端、Ollama和PostgreSQL。 Yarn 4通过Corepack自动安装在Docker容器中，无需本地安装。
# Clone repository
git clone https://github.com/your-username/goodocs-mcp.git
cd goodocs-mcp
# Sync environment file
make sync-env
# Edit .env and set DB_PASS
# DB_PASS=your_secure_password_here
# Start all services (backend, Ollama, PostgreSQL)
# Yarn 4 will be automatically installed in the Docker container
make docker-up-full
# Check services status
make docker-ps
# View logs
make docker-logs-full
# Stop all services
make docker-down-full注： 使用Docker时，您不需要在本地安装Yarn——所有事情都会通过Corepack在容器中自动发生。
服务：
- 后端API：http://localhost:3000/api/v1
- Swagger用户界面：http://localhost:3000/api/v1/docs
- 奥拉玛：http://localhost:11434
看 医生.md 了解详细的Docker设置说明。
方案2：地方发展
对于没有Docker的本地开发：
先决条件：
- Node.js 18+（启用Corepack）
- Docker和Docker Compose（仅适用于PostgreSQL）
- Ollama在当地安装
# Clone repository
git clone https://github.com/your-username/goodocs-mcp.git
cd goodocs-mcp
# Setup Yarn 4 and install dependencies
make install
# Or step by step:
# make setup-yarn # Setup Yarn 4 via Corepack
# make sync-env # Sync environment file
# yarn install # Install dependencies
# Start PostgreSQL with pgvector
make docker-up
# Install and start Ollama locally
# macOS: brew install ollama && brew services start ollama
# Linux: curl -fsSL https://ollama.com/install.sh | sh && ollama serve
# Download model: ollama pull nomic-embed-text
# Build project
yarn build
# Start server
yarn start:dev配置
- 数据库配置 (
.env):
DB_HOST=localhost
DB_PORT=5433
DB_USER=goodocs_mcp_user
DB_PASS=your_password
DB_NAME=goodocs_mcp_db
DB_SYNC=true- AI配置 (
.env):
# Choose embedding provider: openai, ollama, deepseek, cohere, google
AI_MODEL=openai
# For OpenAI
OPENAI_API_KEY=sk-...
# For Ollama (local, free)
# AI_MODEL=ollama
# OLLAMA_BASE_URL=http://localhost:11434
# OLLAMA_EMBEDDING_MODEL=nomic-embed-text
# For DeepSeek
# AI_MODEL=deepseek
# DEEPSEEK_API_KEY=sk-...看 .docs/嵌入式_替代方案.md 了解详细的配置选项。
📖 用法
REST API
服务器提供了带有Swagger文档的REST API，位于 http://localhost:3000/api/v1/docs.
异步索引
# Create indexing task
curl -X POST http://localhost:3000/api/indexer/index \
-H "Content-Type: application/json" \
-d '{"url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript"}'
# Response: {"taskId": "...", "status": "pending", ...}
# Check task status
curl http://localhost:3000/api/indexer/tasks/{taskId}
# Response: {"status": "completed", "progress": 100, "result": {...}}看 .docs/INDEXER_API.md 获取完整的API文档。
MCP协议
服务器实现了MCP协议，用于与AI客户端（Claude Desktop、Cursor AI等）集成。
可用工具
index_documentation-创建异步任务以索引文档
- 参数： url （字符串）或 urls （字符串\[\]）， reindex （布尔值） - 退货： taskId 用于状态跟踪
get_task_status-获取索引任务状态
- 参数： taskId （字符串） - 返回：任务状态，包括进度和结果
search_content-在索引文档中搜索
- 参数： query （字符串）， limit （编号） - 返回：具有相关性得分的搜索结果
analyze_concept-分析具体概念
- 参数： concept （字符串）， context （字符串，可选） - 回报：详细分析
explain_learning-学习辅助
- 参数： topic （字符串）， level （字符串：“初级”|“中级”|“高级”） - 返回：指定级别的解释
get_indexed_stats-获取索引统计信息
- 返回：文档总数、块数、URL、最后索引日期
连接到Cursor IDE
要将GoodDocs MCP服务器连接到Cursor IDE：
先决条件：
- 已安装Docker和Docker Compose
- 在Docker中运行的GoodDocs MCP服务器(
make docker-up-full) - 已安装游标IDE
步骤1：验证容器是否正在运行
docker ps | grep goodocs-mcp-mcp如果没有运行，请启动它：
make docker-up-full步骤2：配置游标
为Cursor创建或编辑MCP配置文件：
macOS/Linux：
mkdir -p ~/.cursor/mcp窗户：
%APPDATA%\Cursor\mcp\创建一个 config.json 此目录中的文件：
{
"mcpServers": {
"goodocs-mcp": {
"command": "docker",
"args": [
"exec",
"-i",
"goodocs-mcp-mcp",
"node",
"dist/main.js",
"--mcp"
],
"env": {}
}
}
}步骤3：重新启动游标
关闭并重新打开Cursor IDE以应用更改。
步骤4：验证连接
在光标中，打开MCP面板或尝试使用MCP命令。您应该看到上面列出的可用工具。
备选方案：地方发展方案
如果你想在本地运行MCP服务器（不使用Docker），请参阅 CURSOR_MCP_SETUP.md 详细说明。
快速设置： 看 CURSOR_SETUP_QUICK.md 快速参考指南。
看 .docs/MCP_USAGE.md 了解详细的MCP使用说明。
🏗️ 建筑
技术栈
- 框架-NestJS
- 数据库：带pgvector的PostgreSQL
- 对象关系映射：TypeORM
- API 文档：Swagger/OpenAPI
- 嵌入：OpenAI、Ollama、DeepSeek、Cohere、谷歌
项目结构
goodocs-mcp/
├── src/
│ ├── main.ts # Entry point
│ ├── app.module.ts # Main application module
│ ├── config/ # Configuration module
│ │ ├── ai-config.ts # AI provider configuration
│ │ ├── database-config.ts # Database configuration
│ │ └── types/ # Configuration types
│ ├── database/ # Database module
│ │ ├── database.module.ts
│ │ └── migrations/ # Database migrations
│ ├── entities/ # TypeORM entities
│ │ ├── document-chunk.entity.ts
│ │ └── indexing-task.entity.ts
│ ├── dto/ # Data Transfer Objects
│ ├── indexer/ # Indexing module
│ │ ├── indexer.service.ts # Main indexing logic
│ │ ├── indexing-task.service.ts # Task queue management
│ │ ├── indexer.controller.ts # REST API endpoints
│ │ ├── crawler.service.ts # HTML fetching
│ │ ├── cleaner.service.ts # Content extraction
│ │ └── chunker.service.ts # Text chunking
│ ├── storage/ # Storage module
│ │ ├── storage.service.ts # PostgreSQL storage
│ │ └── mappers/ # Entity mappers
│ ├── searcher/ # Search module
│ │ ├── searcher.service.ts # Search logic
│ │ └── embedder.service.ts # Embedding generation
│ ├── analyzer/ # Analysis module
│ │ └── analyzer.service.ts # AI-powered analysis
│ └── mcp/ # MCP protocol module
│ └── mcp.service.ts # MCP handlers
├── .docs/ # Documentation
│ ├── INDEXER_API.md # REST API documentation
│ ├── MCP_USAGE.md # MCP protocol guide
│ ├── EMBEDDING_ALTERNATIVES.md # Embedding providers
│ └── ASYNC_INDEXING.md # Async indexing architecture
├── scripts/ # Utility scripts
│ ├── test-embedding.js # Test embedding generation
│ ├── test-ollama.js # Test Ollama setup
│ └── test-mcp-client.js # Test MCP client
├── docker-compose.yml # Docker Compose configuration (Backend + Ollama + PostgreSQL)
├── Dockerfile # Backend Docker image
├── docker-entrypoint-ollama.sh # Ollama initialization script
├── DOCKER.md # Docker setup documentation
├── init-scripts/ # Database init scripts
└── package.json关键模块
索引器模块
- 索引器服务 -编排索引过程
- 索引任务服务 -管理异步任务队列
- 索引器控制器 -用于索引的REST API
- 爬虫服务 -获取HTML内容
- 清洁服务 -提取结构化内容
- Chunker服务 -将文本分割成块
存储模块
- 存储服务 -PostgreSQL存储实现
- 使用向量嵌入存储文档块
- 管理索引任务
搜索模块
- 搜索服务 -语义和关键字搜索
- 嵌入服务 -多提供商嵌入生成
- 支持：OpenAI、Ollama、DeepSeek、Cohere、谷歌
分析器模块
- 分析仪服务 -基于人工智能的概念分析
- 使用SearcherService进行上下文检索
🔧 发展
脚本
# Development
yarn start:dev # Start with hot reload
yarn start:debug # Start with debug mode
# Build
yarn build # Build for production
yarn start:prod # Start production build
# Testing
yarn test # Run tests
yarn test:watch # Watch mode
yarn test:cov # CoverageDocker命令（Makefile）
# Environment
make sync-env # Sync env.example to .env files
make sync-env MODE=production # Sync with production mode
# Full stack (Backend + Ollama + PostgreSQL)
make docker-up-full # Start all services
make docker-down-full # Stop all services
make docker-logs-full # View all services logs
# PostgreSQL only
make docker-up # Start PostgreSQL
make docker-down # Stop PostgreSQL
make docker-restart # Restart PostgreSQL
make docker-logs # View PostgreSQL logs
make docker-ps # Show running containers
make docker-shell # Open PostgreSQL shell
# Help
make help # Show all available commands数据库设置
# Start PostgreSQL (local development)
make docker-up
# Check connection
make docker-ps
# Tables are created automatically when DB_SYNC=true测试嵌入
# Test OpenAI
node scripts/test-embedding.js
# Test Ollama
node scripts/test-ollama.js
# Test MCP client
node scripts/test-mcp-client.js index "https://example.com"📚 文档
- REST API文档 -完整的API参考
- MCP使用指南 -MCP协议集成
- 嵌入替代方案 -替代提供商设置
- 异步索引 -异步索引架构
🔐 环境变量
看 env.example 对于所有可用的配置选项。
关键变量：
AI_MODEL-嵌入提供商（openai、ollama、deepseek、coheres、谷歌）OPENAI_API_KEY-OpenAI API密钥DB_*-数据库配置SWAGGER_ENABLED-启用/禁用Swagger UI
🐳 码头工人
全栈（后端+Ollama+PostgreSQL）
使用Makefile命令在Docker中运行所有内容：
# Start all services
make docker-up-full
# View logs
make docker-logs-full
# View specific service logs
docker-compose logs -f backend
docker-compose logs -f ollama
docker-compose logs -f postgres
# Check services status
make docker-ps
# Stop all services
make docker-down-full
# Stop and remove volumes (⚠️ deletes data)
docker-compose down -v或者直接使用docker compose：
docker-compose up -d
docker-compose logs -f
docker-compose down看 医生.md 查看完整的Docker文档。
仅限PostgreSQL
如果你只想在Docker中运行PostgreSQL：
# Start only PostgreSQL
make docker-up
# View logs
make docker-logs
# Stop PostgreSQL
make docker-down
# Open PostgreSQL shell
make docker-shell🎯 详细功能
异步索引
- 任务队列：具有PostgreSQL持久性的内存任务队列
- 进度跟踪：实时进度更新（0-100%）
- 状态管理：待定→ 处理→ 已完成/失败
- 批处理：支持多个URL
- 重新索引：删除旧块并重新索引
多提供商嵌入
- 开放人工智能 -高品质，付费
- 奥拉玛 -本地、免费、私人
- 深度求索 -经济高效的替代方案
- 凝聚 -专注于嵌入
- 谷歌 -顶点AI/双子座
PostgreSQL存储
- pg向量 -向量相似性搜索
- 类型ORM -类型安全的数据库访问
- 迁移 -数据库模式管理
- 索引 -针对搜索性能进行了优化
🔧 故障排除
Yarn未安装或版本错误
对于Docker： 纱线会自动安装在容器中。如果遇到问题，请重建映像：
docker-compose build --no-cache backend
docker-compose up -d对于当地发展： 如果运行时出错 yarn install 或未找到Yarn：
# 1. Make sure Corepack is enabled
corepack enable
# 2. Install Yarn 4 automatically
bash scripts/setup-yarn.sh
# Or manually:
corepack prepare yarn@4.9.0 --activate
# 3. Check version
yarn --version # Should be 4.9.0问题： yarn: command not found
- 解决方案： 确保Corepack已启用：
corepack enable
问题： Yarn version mismatch
- 解决方案： 跑
corepack prepare yarn@4.9.0 --activate
问题： PnP not configured
- 解决方案： 该项目使用
node-modules模式（非PnP）。这很正常。检查.yarnrc.yml-应该是nodeLinker: node-modules
依赖性问题
对于Docker： 依赖关系会在Docker构建过程中自动安装。如果 yarn.lock 如果已过时，它将自动更新。无需手动操作。
对于当地发展：
# Clear cache and reinstall
rm -rf node_modules .yarn/cache
yarn installDocker问题
# Recreate containers
make docker-down-full
docker system prune -f
make docker-up-full🤝 贡献
欢迎投稿！请随时提交拉取请求。
重要提示： 此存储库使用分支保护。所有捐款必须通过Pull Requests提交。直接推动 main 不允许分支。
看 贡献.md 详细的贡献指南。
📄 许可证
该项目是开源的，可在 MIT许可证.
版权所有（c）2025 GoodDocs MCP贡献者
特此免费向任何获得副本的人授予许可 本软件和相关文档文件（“软件”），以处理 在软件中不受限制，包括但不限于权利 使用、复制、修改、合并、发布、分发、再许可和/或销售 软件的副本，并允许软件的接收者 根据以下条件提供：
上述版权声明和本许可声明应包含在所有 软件的副本或实质性部分。
软件按“原样”提供，不提供任何形式的明示或明示担保 隐含的，包括但不限于适销性保证， 适用于特定目的且不造成伤害。在任何情况下 作者或版权持有人对任何索赔、损害赔偿或其他 因以下原因产生的责任，无论是在合同、侵权或其他诉讼中， 出于或与软件、使用或其他交易有关 软件。