Doc Bridge MCP

🧠 DocBridge MCP——基于Claude MCP的调试助手

使用构建的AI驱动调试助手 模型上下文协议（MCP） 直接与 克劳德桌面，帮助开发人员查询文档、分析问题并加快调试工作流程。

______________________________________________________________________

1.🧩 问题陈述

根据最近的行业调查， 开发人员花费超过40%的时间调试或搜索文档 而不是航运功能。这种生产力的损失转化为软件交付的重大延误，并增加了开发团队的挫败感。

挑战：

• 手动文档搜索既耗时又零散
• 调试工作流需要在IDE和浏览器之间不断切换上下文
• 大多数调试助手依赖于通用搜索，而不了解您的特定代码库

DocBridge MCP解决了这个问题 通过将即时的、基于人工智能的文档查找直接引入您的对话式编码伙伴Claude Desktop。

______________________________________________________________________

2.💡 动机

DocBridge MCP背后的动机是通过以下方式弥合开发人员和文档之间的差距：

• 构建本地MCP服务器 无缝连接到Claude Desktop，无需外部API开销
• 使Claude能够动态获取文档 通过自定义工具调用，在对话中保持上下文
• 为自调试代理创建基础 它可以在未来的迭代中自主分析日志、回溯和错误
• 减少上下文切换 通过让开发人员保持在IDE助手流程中

该项目演示了MCP服务器如何使用为开发人员工作流量身定制的领域特定工具扩展Claude的功能。

______________________________________________________________________

3.⚙️ 使用的工具和技术栈

获取API密钥

Groq API密钥：

1. 访问 https://console.groq.com/keys
2. 使用谷歌或电子邮件注册
3. 单击“创建API密钥”
4. 复制密钥并安全保存

Serper API密钥：

1. 访问 https://serper.dev/
2. 免费注册（包括100次免费搜索）
3. 转到仪表板中的API关键部分
4. 复制API密钥

______________________________________________________________________

4.🚀 如何运行此项目

先决条件

• Python 3.10或更高版本
• 已安装Claude Desktop
• 有效的Groq和Serper API密钥

安装和设置

选项A：使用 uv （推荐-更快）

步骤1：安装 uv 包管理器

pip install uv

步骤2：在Windows上克隆和安装

git clone https://github.com/Vibhuarvind/DocBridge-MCP.git
cd DocBridge-MCP
uv venv .venv
.venv\Scripts\activate
uv sync

步骤2：在macOS/Linux上克隆和设置

git clone https://github.com/Vibhuarvind/DocBridge-MCP.git
cd DocBridge-MCP
uv venv .venv
source .venv/bin/activate
uv sync

选项B：使用 pip （传统）

步骤1:在Windows上克隆和安装

git clone https://github.com/Vibhuarvind/DocBridge-MCP.git
cd DocBridge-MCP
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

步骤1：在macOS/Linux上克隆和设置

git clone https://github.com/Vibhuarvind/DocBridge-MCP.git
cd DocBridge-MCP
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

提示： uv 速度快10-100倍，处理依赖关系的能力更好。强烈推荐！

环境变量

创建一个 .env 项目根目录中的文件：

SERPER_API_KEY=your-serper-api-key-here
GROQ_API_KEY=your-groq-api-key-here

或者直接导出它们：

Windows（PowerShell）：

$env:SERPER_API_KEY="your-serper-api-key-here"
$env:GROQ_API_KEY="your-groq-api-key-here"

macOS/Linux（Bash/Zsh）：

export SERPER_API_KEY="your-serper-api-key-here"
export GROQ_API_KEY="your-groq-api-key-here"

运行服务器

在Windows上：

python mcp_server.py

在macOS/Linux上：

python3 mcp_server.py

您应该看到如下输出：

[INFO] MCP Server initialized
[INFO] Tool 'get_docs' registered successfully
[INFO] Server listening on stdio transport

调试日志

所有日志都是在 logs/ 目录：

logs/
├── mcp_server.log          # Main server logs
├── tool_calls.log          # Tool invocation traces
└── api_responses.log       # API response data

实时监控日志：

窗户：

Get-Content logs/mcp_server.log -Wait

macOS/Linux：

tail -f logs/mcp_server.log

______________________________________________________________________

5.🧪 调试和Claude设置

步骤1：在Claude Desktop中配置MCP服务器

1. 打开 克劳德桌面
2. 首选 设置→ 开发者→ 本地MCP服务器
3. 点击 编辑配置 （打开配置文件）
4. 添加此JSON配置：

对于Windows：

{
    "mcpServers": {
        "docs-mcp": {
            "command": "C:\\Users\\YourUsername\\DocBridge-MCP\\.venv\\Scripts\\python.exe",
            "args": ["C:\\Users\\YourUsername\\DocBridge-MCP\\mcp_server.py"],
            "cwd": "C:\\Users\\YourUsername\\DocBridge-MCP",
            "env": {
                "SERPER_API_KEY": "your-serper-api-key-here",
                "GROQ_API_KEY": "your-groq-api-key-here"
            }
        }
    }
}

对于macOS/Linux：

{
    "mcpServers": {
        "docs-mcp": {
            "command": "/Users/your-username/DocBridge-MCP/.venv/bin/python",
            "args": ["/Users/your-username/DocBridge-MCP/mcp_server.py"],
            "cwd": "/Users/your-username/DocBridge-MCP",
            "env": {
                "SERPER_API_KEY": "your-serper-api-key-here",
                "GROQ_API_KEY": "your-groq-api-key-here"
            }
        }
    }
}

1. 保存文件并 重新启动克劳德桌面
2. 你应该看看 docs-mcp — running ✅ 在状态指示器中

第二步：了解工具调用

配置后，Claude将自动检测您的MCP工具。你可以在对话中自然地调用它：

可用工具：

get_docs(query: string) — Fetches relevant documentation based on your query

当您询问有关文档或调试问题的问题时，Claude将调用此工具。该工具返回结构化文档片段、链接和代码示例。

第三步：玩具示例提示

✅ 积极情景：找到文档

您的提示：

Use get_docs to find how to connect LangChain with ChromaDB for vector storage.

预期产量：

Found relevant documentation on LangChain-ChromaDB integration:

1. Installation:
   pip install langchain chroma-db

2. Basic Setup:
   from langchain.vectorstores import Chroma
   from langchain.embeddings import OpenAIEmbeddings
   
   embeddings = OpenAIEmbeddings()
   vectorstore = Chroma.from_documents(
       documents=docs,
       embedding=embeddings
   )

3. Reference Links:
   - https://python.langchain.com/docs/integrations/vectorstores/chroma
   - https://docs.trychroma.com/

The tool successfully retrieves documentation and Claude explains how to integrate
these two libraries for your vector database needs.

______________________________________________________________________

❌ 负面情况：找不到文档

您的提示：

Use get_docs to find recipes for baking chocolate chip cookies.

预期产量：

I don't have relevant technical documentation for that query.

DocBridge-MCP is designed for software development and debugging topics.
Please try queries like:
- "How to set up Docker containers"
- "FastAPI database connection patterns"
- "Python async/await best practices"

This validates that your tool properly filters non-technical queries and
provides helpful guidance when documentation isn't available.

______________________________________________________________________

步骤4：使用MCP检查器进行调试

MCP检查器是用于可视化和调试MCP服务器通信的强大工具。它确切地显示了Claude向服务器发送的内容以及返回的响应。

安装并运行MCP检查器：

npx @modelcontextprotocol/inspector

这将打开一个交互式web界面，您可以在其中：

MCP检查器的特点：

• 查看实时请求 --查看Claude发送到MCP服务器的JSON有效载荷
• 检查响应 --实时查看服务器的响应
• 调试工具调用 --跟踪工具调用参数和返回值
• 监测性能 -检查API响应时间和瓶颈
• 手动测试工具 --无需Claude即可直接调用工具进行测试
• 捕捉错误 --立即查看格式错误的响应、超时和异常

为什么使用它：

1. 调试集成问题 --如果Claude没有调用您的工具，MCP Inspector会显示原因
2. 性能监控 -识别缓慢的API调用或数据处理瓶颈
3. 响应验证 --确保您的工具返回格式正确的JSON
4. 开发工作流程 --MCP服务器开发过程中的更快迭代
5. 错误跟踪 --在问题到达克劳德之前发现并解决问题

示例：调试失败的工具调用

如果你让克劳德使用 get_docs 但它失败了，MCP检查器显示：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_docs",
    "arguments": {
      "query": "Python async patterns"
    }
  }
}

回应：

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Found documentation on async patterns..."
      }
    ]
  }
}

______________________________________________________________________

6.🚀 未来的增强功能

支持AI的HTML抓取策略

目前，文档抓取是静态的。愿景是使其智能化：

概念：

# Instead of manual parsing:
raw_html = fetch_documentation_page(url)
relevant_content = parse_html_with_regex(raw_html)  # Brittle & limited

# Use AI-powered extraction:
raw_html = fetch_documentation_page(url)
response = llm_function(f"Extract setup instructions from: {raw_html}")
relevant_content = response.text

处理臃肿的反应：

当LLM返回详细的HTML解析结果时，使用分块策略：

def chunk_response(response_text, chunk_size=500):
    """Split long responses into manageable chunks"""
    chunks = [
        response_text[i:i+chunk_size] 
        for i in range(0, len(response_text), chunk_size)
    ]
    return chunks

# Process each chunk for relevance scoring
for chunk in chunks:
    relevance_score = score_chunk_relevance(chunk, user_query)
    if relevance_score > threshold:
        use_chunk_in_response(chunk)

这确保了：

• AI仅从臃肿的HTML中提取相关部分
• 分块策略处理内存限制
• 相关性评分优先考虑有用信息
• 用户获得简洁、可操作的答案

计划的功能

• 异步API请求 --同时处理多个文档查询而不会阻塞
• 智能缓存 --存储经常访问的文档以供即时检索
• 代码分析 --分析错误回溯并自动提出修复建议
• 多代理调试 --使用LangGraph编排多个专门的调试代理
• 自定义文档源 --允许用户注册自己的文档URL
• 对话记忆 --跨调试会话维护上下文

生产就绪版本（即将发布）

下一个版本将包括：

• 并发请求的完整异步/等待实现
• 服务器启动前的全面配置验证
• 环境变量架构检查
• 基于LangGraph的多代理编排框架
• 单元测试和集成测试
• Docker容器化，易于部署
• 性能基准和优化

______________________________________________________________________

7.📚 来源和参考

该项目建立在以下基础之上：

• MCP文件： https://modelcontextprotocol.io/docs/develop/build-server --核心协议规范和工具构建模式
• MCP Weather API示例： https://modelcontextprotocol.io/docs/develop/build-server#weather-api问题 --理解工具响应结构的参考实现
• Claude桌面设置： https://claude.ai/docs --集成指南和最佳实践
• 软件调试标准： 加上 debug.py 用于遵循行业最佳实践的标准化错误处理、响应日志记录和调试工作流

关键学习资源

• Anthropic的模型上下文协议规范
• 软件工程调试方法
• API集成模式和错误处理
• 用于并发操作的异步Python模式

______________________________________________________________________

📁 项目结构

DocBridge-MCP/
├── mcp_server.py              # Main MCP server with tool registration
├── debug.py                   # Standardized debugging & logging utilities
├── requirements.txt           # Python dependencies
├── .env                       # Environment variables (API keys)
├── .gitignore                 # Git ignore rules
├── logs/                      # Debug logs (auto-generated)
│   ├── mcp_server.log
│   ├── tool_calls.log
│   └── api_responses.log
└── README.md                  # This file

______________________________________________________________________

🔧 故障排除

问题：“docs-mcp--错误❌"

解决方案： 验证Claude Desktop配置中的路径是否使用绝对路径（而不是相对路径）：

"command": "C:\\Users\\YourName\\DocBridge-MCP\\.venv\\Scripts\\python.exe"

检查日志：

tail -f logs/mcp_server.log

问题：API密钥错误

解决方案： 验证密钥是否已设置：

# Windows
echo %SERPER_API_KEY%
echo %GROQ_API_KEY%

# macOS/Linux
echo $SERPER_API_KEY
echo $GROQ_API_KEY

两者都应该打印你的钥匙。如果为空，请将其设置为 .env 或环境。

问题：未调用工具

解决方案： 更新配置后，完全重新启动Claude Desktop。检查MCP检查器是否有错误：

npx @modelcontextprotocol/inspector

问题：响应缓慢

解决方案： 在中监视API响应时间 logs/api_responses.log.考虑：

• 检查Groq/Sepper API状态
• 降低查询复杂性
• 为重复查询启用缓存

______________________________________________________________________

✨ 作者

维迪莎·阿尔温德\ *M.数据科学技术|人工智能爱好者|构建人工智能辅助开发工具*

______________________________________________________________________

📄 许可证

这个项目是开源的。看 LICENSE 文件以获取详细信息。

______________________________________________________________________

💬 反馈与贡献

发现bug了吗？有一个功能想法吗？在GitHub上打开问题或提交拉取请求！

存储库：