Documee MCP

Documee MCP 服务器

在几秒钟内将任何代码库转换为可教的课程平台。

一个专业的模型上下文协议（MCP）服务器，为AI助手提供上帝模式功能，用于代码库分析和课程生成。采用FastMCP构建，简化服务器实现，三层缓存实现超快性能。

🚀 快速开始

# 1. Clone and navigate to project
cd documee-mcp

# 2. Create virtual environment (Python 3.12+)
python -m venv venv

# 3. Activate virtual environment
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# 4. Install dependencies
pip install -r requirements.txt

# 5. Run the server
python -m src.server

# 6. Test with MCP Inspector
npx @modelcontextprotocol/inspector python -m src.server

⚡ 上帝模式表演

Documee MCP服务器通过智能缓存、并行处理和循证验证实现了“上帝模式”性能：

• 快20倍 初步分析（2-3s vs 30-100s）
• 快450倍 缓存操作（0.1秒vs 45秒）
• 99%准确率 有信心分数
• 70%+缓存命中率 初始扫描后
• 0%幻觉 通过循证验证进行评分

📋 目录

• 安装
• 项目结构
• 架构概述
• 用法示例
• 配置
• 绩效目标
• 测试
• 整合
• 故障排除
• 文档

📦 安装

先决条件

• Python 3.12或更高版本 （必填）
• Node.js 18+ （用于MCP检验员测试）
• Git （用于克隆存储库）

分步安装

1.验证Python版本

python --version
# Should output: Python 3.12.0 or higher

如果你没有Python 3.12，请从以下网址下载 python.org.

2.克隆存储库

git clone https://github.com/yourusername/documee-mcp.git
cd documee-mcp

3.创建虚拟环境

窗户：

python -m venv venv
venv\Scripts\activate

macOS/Linux：

python -m venv venv
source venv/bin/activate

你应该看看 (venv) 在您的终端提示中。

4.安装依赖项

pip install -r requirements.txt

这将安装：

• fastmcp>=0.5.0 -用于简化MCP服务器实现的FastMCP框架
• aiofiles>=23.2.1 -异步文件I/O
• aiosqlite>=0.19.0 -异步SQLite数据库
• pyyaml>=6.0.1 -YAML配置解析
• python-dotenv>=1.0.0 -环境变量管理
• pytest>=7.4.3 -测试框架
• pytest-asyncio>=0.21.1 -异步测试支持
• pytest-cov>=4.1.0 -代码覆盖率报告

5.验证安装

# Check if server starts
python -m src.server --help

# Run tests
pytest tests/ -v

可选：安装MCP检查器

用于测试和调试：

npm install -g @modelcontextprotocol/inspector

🏗️ 项目结构

documee-mcp/
├── src/                          # Source code
│   ├── server.py                 # MCP server entry point (FastMCP)
│   ├── tools/                    # MCP tool implementations
│   │   ├── scan_codebase.py      # Codebase structure scanner
│   │   ├── detect_frameworks.py  # Framework detection
│   │   └── discover_features.py  # Feature discovery
│   ├── cache/                    # Caching system
│   │   └── unified_cache.py      # 3-tier cache manager
│   ├── models/                   # Data models
│   │   └── schemas.py            # Dataclasses for results
│   ├── utils/                    # Utility functions
│   │   ├── file_utils.py         # File operations
│   │   └── path_utils.py         # Path sanitization
│   └── config/                   # Configuration
│       └── settings.py           # Settings management
├── tests/                        # Test suite
│   ├── test_cache.py             # Cache tests
│   ├── test_scan_codebase.py     # Scanner tests
│   ├── test_detect_frameworks.py # Framework detection tests
│   └── test_discover_features.py # Feature discovery tests
├── cache_db/                     # SQLite cache storage
│   └── cache.db                  # Persistent cache database
├── examples/                     # Usage examples
│   ├── basic_usage.py            # Basic MCP client example
│   ├── kiro_config.json          # Kiro integration config
│   └── claude_config.json        # Claude Desktop config
├── docs/                         # Documentation
│   ├── ULTIMATE-MCP-SERVER.md    # Complete implementation guide
│   ├── GOD-MODE-TOOLKIT.md       # Vision and capabilities
│   └── QUICK-START-GUIDE.md      # 5-minute quick start
├── config.yaml                   # Server configuration
├── requirements.txt              # Python dependencies
└── README.md                     # This file

🏛️ 架构概述

高级体系结构

┌─────────────────────────────────────────────────────────────┐
│                        AI Client                             │
│                  (Claude, GPT, Kiro)                         │
└────────────────────────┬────────────────────────────────────┘
                         │ JSON-RPC 2.0 over stdio
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                    MCP Server Core                           │
│                     (FastMCP)                                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   Tools      │  │  Resources   │  │   Prompts    │      │
│  │  (3 tools)   │  │ (2 resources)│  │  (1 prompt)  │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│              UnifiedCacheManager (3-Tier)                    │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ Memory (LRU) │→ │    SQLite    │→ │Redis (opt.)  │      │
│  │   1000ms
  slow_operation_threshold_ms: 1000

logging:
  level: INFO                     # DEBUG, INFO, WARNING, ERROR
  file: server.log                # Log file path
  max_size_mb: 10                 # Log rotation size
  backup_count: 3                 # Number of backup logs

环境变量

用环境变量覆盖配置：

# Cache settings
export CACHE_MAX_SIZE_MB=1000
export REDIS_URL=redis://localhost:6379

# Analysis settings
export MAX_FILE_SIZE_MB=20
export MAX_DEPTH=15

# Logging
export LOG_LEVEL=DEBUG

优先： 环境变量>config.yaml>默认值

默认值

如果没有提供配置，则使用这些默认值：

• max_memory_mb: 500
• sqlite_path：cache_db/cache.db
• redis_url：无（禁用）
• max_file_size_mb: 10
• max_depth: 10
• log_level：信息

🎯 绩效目标

上帝模式绩效目标

Documee MCP服务器旨在实现“上帝模式”性能：

性能基准

# Run performance benchmarks
pytest tests/test_performance_validation.py -v

# Expected results:
# - scan_codebase (1000 files): 2.5s first run, 0.08s cached
# - detect_frameworks: 2.1s first run, 0.05s cached
# - discover_features: 3.8s first run, 0.06s cached
# - Complete workflow: 10.2s first run, 0.15s cached

高速缓存性能

三层缓存系统提供：

• 内存（第1层）：小于0.001秒的访问时间
• SQLite（第2层）：\ 70% target

### MCP检验员测试

MCP Inspector是Anthropic用于验证MCP服务器的官方测试工具。

#### 安装MCP检查器

npm install -g @modelcontextprotocol/inspector

#### 启动检查器

npx @modelcontextprotocol/inspector python -m src.server

这将打开一个web界面 `http://localhost:5173` 您可以在哪里：

1. **列出工具** -查看所有3个已注册的工具
1. **列出资源** -查看2个已注册资源
1. **列表提示** -查看1个注册提示
1. **调用工具** -具有自定义参数的测试工具
1. **阅读资源** -访问缓存数据
1. **获取提示** -查看提示模板

#### 测试场景

**测试1：扫描代码库**

{ "path": ".", "max_depth": 5, "use_cache": true }

**测试2：检测框架**

{ "codebase_id": "", "confidence_threshold": 0.7, "use_cache": true }

**测试3：发现功能**

{ "codebase_id": "", "categories": ["routes", "api"], "use_cache": true }

**测试4：读取资源**

- 资源URI: `codebase://structure`
- 应返回缓存的结构数据

**测试5：获取提示**

- 提示名称： `analyze_codebase`
- 论据： `{"codebase_path": "/path/to/project"}`

### 发展模式

对于自动重新加载的开发：

Install uv (if not already installed)

pip install uv

Run in development mode

uv run mcp dev src/server.py

当您更改代码时，这会自动重新加载服务器。

## 🔌 整合

### 与Kiro集成

Kiro是一个支持MCP服务器的AI驱动IDE。

#### 1.创建Kiro配置

创建或编辑 `.kiro/settings/mcp.json` 在您的工作空间中：

{ "mcpServers": { "documee": { "command": "python", "args": ["-m", "src.server"], "cwd": "/absolute/path/to/documee-mcp", "disabled": false, "autoApprove": [ "scan_codebase", "detect_frameworks", "discover_features" ] } } }

或者使用示例配置：

cp examples/kiro_config.json .kiro/settings/mcp.json

#### 2.重新启动Kiro

重新启动Kiro或从MCP服务器视图重新加载MCP服务器。

#### 3.在Kiro中使用

在Kiro聊天中，您现在可以使用以下工具：

Analyze this codebase using the documee MCP server.

Kiro将自动呼叫：

1. `scan_codebase` 理解结构
1. `detect_frameworks` 识别技术栈
1. `discover_features` 寻找可教代码

### 与Claude Desktop集成

Claude Desktop支持MCP服务器以增强功能。

#### 1.创建Claude配置

**窗户：** 编辑 `%APPDATA%\Claude\claude_desktop_config.json`

**macOS：** 编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`

添加Documee服务器：

{ "mcpServers": { "documee": { "command": "python", "args": ["-m", "src.server"], "cwd": "C:\\path\\to\\documee-mcp" } } }

或者使用示例配置：

Copy example config

cp examples/claude_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

#### 2.重新启动克劳德桌面

完全退出并重新启动Claude Desktop。

#### 3.验证连接

在Claude Desktop中，您应该看到🔌 指示MCP服务器已连接的图标。

#### 4.在Claude中使用

让Claude分析代码库：

Please analyze the codebase at /path/to/my/project using the documee MCP server.

Claude将使用可用的工具提供详细的分析。

### 与其他AI客户端集成

任何兼容MCP的AI客户端都可以使用Documee服务器：

1. **配置客户端** 运行 `python -m src.server`
1. **设置工作目录** 到documee mcp文件夹
1. **启用stdio传输** （MCP的默认设置）

## 🐛 故障排除

### 常见问题

#### 问题1：“找不到模块”错误

**症状：**

ModuleNotFoundError: No module named 'fastmcp'

**解决方案：**

Ensure virtual environment is activated

Windows:

venv\Scripts\activate

macOS/Linux:

source venv/bin/activate

Reinstall dependencies

pip install -r requirements.txt

#### 问题2：Python版本太旧

**症状：**

SyntaxError: invalid syntax (type hints)

**解决方案：**

Check Python version

python --version

Must be 3.12 or higher

Download from https://www.python.org/downloads/

#### 问题3：缓存数据库已锁定

**症状：**

sqlite3.OperationalError: database is locked

**解决方案：**

Stop all running server instances

Delete cache database

rm cache_db/cache.db

Restart server

python -m src.server

#### 问题4：扫描时权限被拒绝

**症状：**

PermissionError: [Errno 13] Permission denied: '/path/to/file'

**解决方案：**

- 服务器跳过它无法读取的文件
- 检查文件权限： `ls -la /path/to/file`
- 以适当的权限运行
- 将目录添加到 `blocked_patterns` 在config.yaml中

#### 问题5:MCP检查器无法连接

**症状：**

Failed to connect to MCP server

**解决方案：**

Ensure server starts without errors

python -m src.server

Check for port conflicts

Try different port for inspector

npx @modelcontextprotocol/inspector --port 5174 python -m src.server

Check Node.js version (need 18+)

node --version

#### 问题6：性能缓慢

**症状：**

- 扫描时间>10秒
- 缓存命中率\<50%

**解决方案：**

Check cache statistics

Add to config.yaml:

logging: level: DEBUG

Increase cache size

cache: memory: max_size_mb: 1000

Enable Redis for distributed caching

cache: redis: enabled: true url: redis://localhost:6379

#### 问题7：框架检测不起作用

**症状：**

{ "frameworks": [], "total_detected": 0 }

**解决方案：**

- 确保 `package.json` 或 `requirements.txt` 存在于项目根目录中
- 检查文件是否为有效的JSON/text
- 验证是否首先扫描了代码库： `scan_codebase` 必须提前致电 `detect_frameworks`
- 检查置信阈值（默认值0.7）

### 调试模式

启用调试日志记录以进行详细诊断：

Set environment variable

export LOG_LEVEL=DEBUG

Or in config.yaml:

logging: level: DEBUG

Run server

python -m src.server

调试日志包括：

- 缓存命中/未命中
- 文件 操作
- 参数值
- 执行时间
- 错误堆栈跟踪

### 获取帮助

如果您遇到此处未涵盖的问题：

1. **检查日志**: `server.log` 包含详细的错误信息
1. **运行测试**: `pytest tests/ -v` 验证安装
1. **检查文件**：参见 `docs/` 详细指南文件夹
1. **打开一个问题**: 

## 🛠️ 技术栈

- **Python 3.12+** -带有类型提示的现代Python
- **FastMCP 0.5.0+** -简化的MCP服务器框架
- **所有23.2.1+** -异步文件I/O以提高性能
- **aiosqlite 0.19.0+** -异步SQLite用于持久缓存
- **Pyoyaml 6.0.1+** -YAML配置解析
- **pytest 7.4.3+** -测试框架
- **SQLite** -持久缓存存储
- **瑞迪斯** （可选）-分布式缓存

## 🎓 用例

- **从真实的代码库中学习** -将任何项目转化为课程
- **机载开发人员** -从代码库生成培训
- **文档模式** -提取并教授最佳实践
- **代码审查** -快速了解架构
- **技术写作** -自动生成文档
- **基于人工智能的内容丰富** -通过循证解释、类比和练习，将基础课程转化为丰富的教育材料

## 🤝 贡献

欢迎投稿！看 [贡献.md](CONTRIBUTING.md) 作为指导方针。

## 📄 许可证

MIT许可证-请参阅 [许可证](LICENSE) 了解详情。

## 🔗 链接

- [MCP文件](https://modelcontextprotocol.io)
- [FastMCP文档](https://github.com/jlowin/fastmcp)
- [拟人化MCP SDK](https://github.com/anthropics/mcp)
- [问题追踪器](https://github.com/yourusername/documee-mcp/issues)

## 🌟 明星历史

如果你觉得这很有用，请在repo上加星！

______________________________________________________________________

**内置于❤️ 对于那些想从真实代码中学习的开发人员来说。**