使用说明
🧠 MCP服务器+文档存储系统
通过持久内存、语义搜索和高级任务功能，将您的人工智能从无状态转变为智能。
🎯 任务
构建一个生产就绪的MCP服务器，使AI系统能够：
- ✅ 记住 所有用户交互和文档
- ✅ 理解 文献语境与意义
- ✅ 路线 智能请求（内存优先策略）
- ✅ 合成 来自多个来源的内容
- ✅ 编辑 基于用户反馈的文档
- ✅ 创建 需求中的新文档
- ✅ 执行 复杂的多步骤任务
- ✅ 学习 从每一次互动中
📊 项目状态
第一阶段：MCP基金会 ✅ 完成
- 基本MCP服务器框架
- 质量评分系统（7个因素）
- 内容路由器（5种策略）
- Web搜索集成
- 33个单元测试（全部通过）
- 全面的文件
第2-5阶段：进行中 （即将开始）
- 文档存储和矢量数据库
- 语义搜索
- 文档编辑/创建
- 高级任务执行
- 测试和部署
🚀 快速入门（5分钟）
1.克隆和安装
cd "c:\Users\DELL CORE i5\New folder\mcp"
pip install -r requirements.txt
2.配置
copy .env.example .env
# Add your API keys to .env
3.跑步
python main.py
4.测试
curl http://localhost:8000/health
📚 文档
| 文件 | 目的 |
|---|---|
| QUICKSTART.md | 5分钟设置和常见任务 |
| 阶段1_文件.md | 完成第一阶段的详细信息 |
| 建筑师_GUIDE.md | 一切如何运作 |
📁 关键组件
核心框架
- MCP服务器 (
src/mcp_server/base_server.py)：协议处理程序、工具管理、资源生命周期 - 质量评分员 (
src/mcp_server/quality_scorer.py)：7因素内容评估 - 内容路由器 (
src/content_router/router.py)：智能源选择 - 网络搜索工具 (
src/web_search/web_search_tool.py)：谷歌Gemini集成
基础设施
- 配置 (
config/settings.py)：基于环境的配置 - 日志记录 (
config/logging_config.py)：结构化日志记录 - 协议 (
src/mcp_protocol.py)：请求/响应模式 - 公用事业 (
src/utils.py)：共享类型和助手
测试（33次测试）
tests/test_mcp_server.py-服务器功能tests/test_quality_scorer.py-评分系统tests/test_content_router.py-路由逻辑tests/test_web_search.py-网络搜索工具\
🎯 主要特点
✅ 第一阶段：MCP基金会
基本MCP服务器
- 异步请求/响应处理
- 工具注册和发现
- 中间件支持
- 自定义错误处理
- 资源管理生命周期
质量评分（7个因素）
- 来源可靠性（25%）
- 含量新鲜度（15%）
- 相关性（25%）
- 完整性（15%）
- 准确度（15%）
- 引用次数（3%）
- 用户反馈（2%）
内容路由器（5种策略）
- MEMORY_FIRST:先检查缓存（默认）
- EXTERNAL_FIRST：获取最新信息
- 平衡：全面覆盖
- MEMORY_ONLY：离线模式
- 仅限外部：仅限新数据
Web搜索集成
- Google Gemini API
- 异步执行
- 结果排名
- 模拟测试回退
⏳ 第2-5阶段：高级功能
阶段2：文档存储
- 矢量数据库（ChromaDB+FAISS）
- 文档处理（PDF、DOCX、PPTX、HTML、图像）
- 语义搜索
- 基于使用的优化
阶段3：内存集成
- 文档存储MCP服务器
- 内存优先路由
- 内容综合
- 性能分析
第四阶段：高级功能
- 文档编辑器（编辑/版本控制）
- 文档创建者（根据需求生成）
- 任务执行器（复杂操作）
- 反馈集成
第五阶段：生产准备就绪
- 全面测试（90%+覆盖率）
- 性能优化
- 安全加固
- Docker部署
- Kubernetes配置
💻 API示例
网页搜索
curl -X POST http://localhost:8000/request \
-H "Content-Type: application/json" \
-d '{
"request_id": "req_001",
"method": "execute",
"tool": "web_search",
"params": {"query": "AI trends", "limit": 5}
}'
列出工具
curl http://localhost:8000/tools
服务器运行状况
curl http://localhost:8000/health
统计
curl http://localhost:8000/stats
🧪 测试
# Run all tests
pytest tests/ -v
# Run with coverage
pytest tests/ --cov=src --cov-report=html
# Run specific test file
pytest tests/test_quality_scorer.py -v
# Run single test
pytest tests/test_mcp_server.py::test_server_initialization -v
当前状态：33/33项测试通过✅
📋 成功指标
| 度量 | 目标 | 状态 |
|---|---|---|
| 内存命中率 | >60% | 第2+阶段 |
| 响应时间（内存） | <200ms | 第2+阶段 |
| 响应时间（网络） | <2s | ✅ |
| API成本降低 | >50% | 第3阶段+ |
| 测试覆盖率 | >90% | 第5阶段 |
| 文档处理准确率 | >95% | 第2+阶段 |
| 任务完成成功率 | >90% | 第4+阶段 |
🔧 配置
中的关键设置 .env:
# Server
ENVIRONMENT=development
MCP_HOST=0.0.0.0
MCP_PORT=8000
# API Keys
GOOGLE_API_KEY=your_key_here
# Performance
VECTOR_SEARCH_K=10
MEMORY_HIT_THRESHOLD=0.7
CACHE_TTL=3600
# Logging
LOG_LEVEL=INFO
DEBUG=True
📚 学习路径
- 阅读: QUICKSTART.md -10分钟
- 跑:
python main.py-5分钟 - 测试:
pytest tests/ -v-5分钟 - 探索: 建筑师_GUIDE.md -20分钟
- 代码：评论
src/mcp_server/base_server.py-30分钟 - 扩展：添加自定义工具-30分钟
🏗️ 建筑
┌─────────────────────────────────────────────────┐
│ REST API (FastAPI) │
│ GET / POST /health /stats /tools /request │
└────────────────┬────────────────────────────────┘
│
┌───────▼────────┐
│ MCP Protocol │
│ Processor │
└───────┬────────┘
│
┌────────────┼────────────┐
│ │ │
▼ ▼ ▼
┌────────┐ ┌──────────┐ ┌──────────┐
│ Web │ │ Quality │ │ Content │
│ Search │ │ Scorer │ │ Router │
│ Tool │ │ (7x) │ │(5 modes) │
└────────┘ └──────────┘ └──────────┘
│ │ │
└────────────┼────────────┘
│
┌────────────▼────────────┐
│ Storage Layer (Phase 2+)
│ - ChromaDB (vectors)
│ - PostgreSQL (metadata)
│ - Redis (cache)
└─────────────────────────┘
🚨 已知限制（第1阶段）
- 无持久存储（在第2阶段添加）
- 无文档处理（第二阶段新增）
- 无矢量数据库（在第2阶段添加）
- 无语义搜索（在阶段2中添加）
- 模拟搜索回退（需要真正的API密钥）
- 无身份验证（在第5阶段添加）
📝 实施时间表
| 阶段 | 持续时间 | 焦点 | 状态 |
|---|---|---|---|
| 1 | 1-2周 | 基础 | ✅ 完成 |
| 2 | 2-3周 | 记忆和向量 | ⏳ 下一个 |
| 3 | 1-2周 | 整合 | 📋 计划中 |
| 4 | 2-3周 | 高级功能 | 📋 计划中 |
| 5 | 2-3周 | 测试和部署 | 📋 计划中 |
🎓 代码示例
创建自定义工具
from src.mcp_server import MCPTool, ToolType
class MyTool(MCPTool):
async def execute(self, params):
# Your code here
return {"result": "success"}
# Register and use
mcp_server.register_tool(MyTool(...))
使用质量评分器
from src.mcp_server import quality_scorer
score = quality_scorer.score_content(
content="...",
source_type="memory",
created_at=datetime.utcnow(),
relevance_score=0.8
)
# Returns: overall_score, quality_level, components
内容路由
from src.content_router import content_router, RoutingStrategy
decision = await content_router.route_request(
query="AI trends",
strategy=RoutingStrategy.MEMORY_FIRST
)
# Returns: sources_to_query, expected_quality, reasoning
📞 支持
- 快速问题：参见 QUICKSTART.md
- 运作原理：参见 建筑师_GUIDE.md
- 详细文档：参见 阶段1_文件.md
- 测试：运行
pytest tests/ -v例如 - 日志：检查
logs/app.log用于故障排除
🎯 后续步骤
- 安装并运行服务器
- 运行测试套件(
pytest tests/ -v) - 尝试API示例（请参见QUICKSTART.md）
- 阅读架构指南
- 使用自定义工具进行扩展
- 第2阶段：添加文档内存和向量
📄 许可证
MIT-见许可证文件（待添加）
👥 贡献
- 复刻仓库
- 创建特征分支
- 为新功能添加测试
- 确保所有测试通过
- 提交拉取请求
使用Python 3.11+、FastAPI、ChromaDB、Docling构建
第一阶段完成！为第二阶段做好准备：文档存储 🚀
