MCP Optimization

MCP优化

MCP优化是启用MCP的LLM工作流的基线与优化工具布线应用程序。

它提供：

• 一 基线管道 （简单/广泛的工具使用）
• 一 优化管道 （意图门+语义排名+top-k工具选择）
• CLI和Streamlit UI中的并排比较
• 持续遥测(runs.db)延迟、工具使用、成本估算和可靠性

______________________________________________________________________

1） 该项目解决的问题

在幼稚的工具调用系统中，模型经常看到太多的工具，并可能过度调用它们。这增加了：

• 响应延迟
• 工具调用计数
• 模型上下文开销
• 总推理成本

该项目引入了一个实用的路由层，在保持正确性的同时减少了不必要的工具暴露。

______________________________________________________________________

2） 端到端架构

flowchart TD
		U[User Query] --> C[client.py Orchestrator]
		C --> M{Mode}

		M -->|baseline| B1[LLM Router]
		B1 --> B2[Tool selection]
		B2 --> B3[Agent with MCP tools]

		M -->|optimized| O1[fast_intent_gate]
		O1 --> O2[semantic_rank_tools]
		O2 --> O3[select_top_k]
		O3 --> O4{deterministic?}
		O4 -->|yes| O5[Direct tool execution]
		O4 -->|no| O6[Agent with shortlisted tools]

		B3 --> F[Final answer]
		O5 --> F
		O6 --> F

		F --> T[metrics.py telemetry]
		T --> DB[(runs.db)]
		DB --> UI[app.py Streamlit Dashboard]
		DB --> BENCH[benchmark.py]

______________________________________________________________________

3） 存储库结构

• client.py\

主异步编排器。支持模式：

- baseline - optimized - compare

• server.py\

MCP服务器公开搜索、翻译和释义工具。

• optimizer.py\

优化策略逻辑：

- fast_intent_gate() - semantic_rank_tools() - select_top_k() - build_optimized_plan()

• tool_catalog.py\

用于排名、默认值和确定性资格的工具元数据。

• metrics.py\

遥测模型+SQLite编写器+令牌/成本提取。

• benchmark.py\

使用来自的查询运行A/B评估 eval_queries.jsonl.

• app.py\

流线型UI，用于并排比较、基准总结和运行历史记录。

• eval_queries.jsonl\

基准查询集。

• requirements.txt\

运行时依赖关系。 (transformers/torch 在当前设置中，路径是可选的。)

______________________________________________________________________

4） 基线流量（当前实施）

flowchart TD
		Q[Query] --> R[ask_router_model]
		R --> D{needs_tools?}
		D -->|no| A1[Direct LLM answer]
		D -->|yes| A2[Agent + selected/all available tools]
		A2 --> A3{Agent failure/timeout?}
		A3 -->|yes| A4[Direct tool fallback + summarization]
		A3 -->|no| A5[Agent final answer]
		A1 --> OUT[Response payload + metrics]
		A4 --> OUT
		A5 --> OUT

笔记：

• 路由器故障退回到安全计划。
• 代理和工具调用受超时保护。
• 错误回退仍然会在可能的情况下返回面向用户的答案。

______________________________________________________________________

5） 优化流程（关键逻辑）

flowchart TD
		Q[Query] --> G[fast_intent_gate]
		G --> H{Needs tools?}
		H -->|no| D1[Direct LLM answer]
		H -->|yes| R[semantic_rank_tools]
		R --> K[select_top_k]
		K --> P[build_tool_args]
		P --> E{Single deterministic tool?}
		E -->|yes| T1[Direct tool execution]
		E -->|no| T2[LLM agent with shortlist]
		T2 --> F{Agent failure/timeout?}
		F -->|yes| T3[Direct tool fallback + summarization]
		F -->|no| T4[Agent final answer]

		D1 --> OUT[Response payload + metrics]
		T1 --> OUT
		T3 --> OUT
		T4 --> OUT

优化意图：

• 减少工具上下文表面
• 减少不必要的工具调用
• 为简单任务保持直接/低延迟路径

______________________________________________________________________

6） MCP服务器工具

搜索

• search_articles
• search_research_papers
• search_lit_reviews

翻译

• translate_japanese
• translate_french
• translate_spanish

改述

• paraphrase_formal
• paraphrase_casual
• paraphrase_academic

______________________________________________________________________

7） 指标和持久性

每次查询运行都会将一行写入 runs.db.

跟踪字段包括：

• mode
• latency_ms
• tools_considered
• selected_tools_count
• tool_calls_executed
• router_confidence
• input_tokens, output_tokens （尽最大努力）
• estimated_cost_usd
• success
• error_type
• selected_tools_json
• metadata_json

度量管道

flowchart LR
		R[Runtime response] --> X[extract_token_usage]
		X --> C[estimate_cost_usd]
		C --> M[QueryMetrics dataclass]
		M --> S[MetricsStore.write]
		S --> DB[(runs.db)]

______________________________________________________________________

8） 比较数学

对于 compare 模式和基准：

$$ ext{latency_improvement_pct}=\\frac{L\_{baseline}-L\_{optimized}{L\_{baseline}\\times 100 $$

$$ ext{tools_reduction_pct}=\\frac{T\_{baseline}-T\_{optimized}{T\_{baseline}\\times 100 $$

$$ ext{cost_improvement_pct}=\\frac{C\_{baseline}-C\_{optimized}{C\_{baseline}}\\times 100 $$

______________________________________________________________________

9） 流线型UI行为

仪表板在 app.py 提供：

1. 实时比较\

基线在顶部，优化在下面，具有突出的指标和状态。

1. 基准总结\

跨部门汇总指标 eval_queries.jsonl.

1. 运行历史\

上次跑步时间 runs.db 以表格形式。

UI流程：

flowchart TD
		U[User clicks Run baseline vs optimized] --> C[compare_query_modes]
		C --> B[baseline handle_user_query]
		C --> O[optimized handle_user_query]
		B --> DB[(runs.db)]
		O --> DB
		C --> V[Render comparison cards + answers]
		DB --> H[Render run history table]

______________________________________________________________________

10） 配置（.env）

创建 .env 在项目根目录中：

GROQ_API_KEY=your_groq_api_key_here

# optional; defaults to ./server.py
MCP_SERVER_PATH=C:/Users/lenovo/Desktop/MCP/MCP-Optimization/server.py

# reliability/performance controls
AGENT_TIMEOUT_SECONDS=60
TOOL_TIMEOUT_SECONDS=20

# arXiv lookup switch in server search path
USE_ARXIV=0

______________________________________________________________________

11） 设置并运行

安装：

pip install -r requirements.txt

运行优化查询：

python client.py --mode optimized --query "Find recent research papers on MCP optimization"

运行基线查询：

python client.py --mode baseline --query "Find recent research papers on MCP optimization"

并排运行比较：

python client.py --mode compare --query "Translate this to Japanese: Thank you for your support"

运行基准测试：

python benchmark.py

启动仪表板：

streamlit run app.py

______________________________________________________________________

12） 可靠性行为和回退

编排器旨在即使在部分故障期间也能返回有用的输出：

• 路由器解析失败→ 备用计划
• 代理超时/失败→ 直接工具回退+摘要
• 外部例外→ 直接模型回退答案
• 服务器工具中缺少可选依赖项→ 优雅的回退消息

______________________________________________________________________

13） 当前限制

• 令牌使用提取取决于提供者的响应形状（尽最大努力）。
• 翻译后端可能因 googletrans 版本/网络行为。
• 搜索质量/延迟可能因外部API响应时间而异。
• 比较结果可能依赖于查询（优化后偶尔会调用更多工具）。

______________________________________________________________________

14） 建议的下一步改进

• 为所选路由器添加严格的架构验证 tool_args.
• 添加每个工具的冷却时间和历史成功权重。
• 添加更丰富的带有正确性标签的评估集。
• 在UI中添加随时间变化的趋势线图表。