MCP Python Poc

MCP RAG POC代理

概念验证模型上下文协议设置，在单个持久RAG知识服务器上具有三个可互换的客户端层。

组件

______________________________________________________________________

系统架构

graph LR
    subgraph Clients
        CLI["client.py\n(RAG CLI)"]
        LG["langgraph_agent.py\n(LangGraph agent)"]
        UI["ui_server.py :8080\n(Browser UI)"]
    end

    subgraph MCP["server.py — MCP Server :8000"]
        KS["KnowledgeStore"]
        IDX["BM25 + trigram\nindex (in-memory)"]
        FS[(".mcp_store/\nknowledge_store.json")]
        KS --- IDX
        KS -. persists .-> FS
    end

    CLI  -->|"MCP HTTP"| MCP
    UI   -->|"HTTP proxy\n(/api/tool)"| MCP
    LG   -->|"langchain-mcp-adapters\nget_tools() + call_tool()"| MCP

______________________________________________________________________

LangGraph代理流

这 langgraph_agent.py 代理使用 create_react_agent 从LangGraph获取工具，并直接从正在运行的MCP服务器获取所有工具，因此代理本身没有工具逻辑。

flowchart TD
    IN(["👤 Human message"]) --> LLM

    subgraph Graph["LangGraph — create_react_agent"]
        direction TB
        LLM["Claude\n(LLM node)"]
        TN["ToolNode\n(MCP tools)"]
        LLM -->|"tool_calls[ ]"| TN
        TN  -->|"ToolMessage"| LLM
    end

    LLM -->|"no tool_calls"| OUT(["💬 AIMessage\n(cited answer)"])

    subgraph Adapter["langchain-mcp-adapters"]
        A["MultiServerMCPClient\n→ LangChain tool wrappers"]
    end

    subgraph Tools["MCP tools (from server.py)"]
        direction LR
        T1["ingest_*"]
        T2["search_knowledge"]
        T3["build_answer_context"]
        T4["list / get *"]
    end

    Adapter -->|"wraps"| Graph
    TN      -->|"HTTP call"| Tools
    Tools   -->|"JSON result"| TN

代理推理循环（每轮）：

1. LLM接收对话历史+系统提示，强制执行有根据的答案。
2. 如果需要证据，它会发出 tool_calls --ToolNode通过HTTP对MCP服务器执行它们。
3. 工具结果以如下形式注入 ToolMessages、 LLM继续推理。
4. 当有信心时，LLM会发出最终的 AIMessage 带有引用的块ID。

______________________________________________________________________

检索评分

search_knowledge 用综合分数对块进行排名：

score = BM25(query, chunk)
      + term_coverage_ratio × 1.5
      + trigram_jaccard     × 2.0
      + exact_phrase_bonus  × 1.75

build_answer_context 然后将前k个块组装成一个有界的证据包（默认6000个字符） [C1]… 引文标签已准备好供法学硕士参考。

______________________________________________________________________

设置

python -m venv .venv && source .venv/bin/activate
pip install fastmcp fastapi uvicorn

# LangGraph agent only:
pip install langgraph langchain-anthropic "langchain-mcp-adapters>=0.1.0"
export ANTHROPIC_API_KEY=

运行MCP服务器

python server.py
# → http://127.0.0.1:8000/mcp

运行确定性客户端

python client.py ingest-dir knowledge          # seed the knowledge base
python client.py ask "What is agentic RAG?"
python client.py search "chunk level evidence"
python client.py chat                          # interactive loop

运行LangGraph代理

python server.py &                             # must be running first
python langgraph_agent.py                      # interactive chat
python langgraph_agent.py ask "your question"
python langgraph_agent.py ingest knowledge/    # ingest a directory

运行浏览器UI

python ui_server.py
# → http://127.0.0.1:8080

UI将所有MCP工具公开为具有实时模式检查和调用历史的交互式表单。

______________________________________________________________________

MCP工具

概述/统计数据

• server_overview --功能和当前商店统计数据
• knowledge_base_stats --块计数、平均令牌长度、文件路径

摄入

• ingest_text_document --摄取带有可选元数据的原始文本
• ingest_file_document --从repo读取文件或 /tmp 并摄入它
• ingest_directory_documents --批量摄取目录（默认值： .md .txt .rst .py .json .yaml .yml)

知识检查

• list_knowledge_documents --所有按新旧程度排序的索引文档
• get_knowledge_document --文档记录+其所有块
• get_knowledge_chunk --包含父文档信息的单个块

检索

• search_knowledge --BM25检索，包括每次点击的评分原因
• build_answer_context --有界证据包 [C1]… 引文标签

______________________________________________________________________

储存和安全

• 所有索引内容都保留在 .mcp_store/knowledge_store.json.
• 文件摄取的范围仅限于repo根目录 /tmp (SAFE_ROOTS).
• LangGraph代理的系统提示强制执行：在回答之前检索、引用块ID、标记低置信度证据。

______________________________________________________________________

建议的后续步骤

• 在相同的工具契约后面添加嵌入支持的检索。
• 添加文档删除和选择性重新索引。
• 将真正的LLM合成层插入确定性 client.py 更丰富的答案。