toolscout (Corradocavalli)

MCPAI代理

提供方 corradocavalli

AI代理 stdio · 本地进程 会话登录 社区 / 第三方 Claude
查看接入方式

ToolScout是一个基于向量相似度搜索和对话历史优化的动态工具发现与执行系统,用于管理大型工具集和优化长对话。

一句话选型结论

按资料字段整理

toolscout (Corradocavalli) 属于AI代理类 MCP 服务器,stdio · 本地进程,会话登录,可直接接入 Claude,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类AI代理 传输方式stdio · 本地进程 鉴权会话登录 部署方式本地部署
GitHub 星标 1 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

AI代理
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

工具发现Python本地部署向量搜索对话优化AI代理上下文管理

安装与配置

stdio · 本地进程 会话登录
客户端在本机拉起子进程,数据不出本机
uv run main.py

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Python,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
给代理接外部能力

让代理在任务中途调用搜索、数据库等真实工具。

多步任务编排

把一串操作拆成步骤,由代理按顺序执行。

自动化重复流程

把固定流程交给代理跑,减少手工操作。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好会话登录对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在AI代理场景里让模型直接调用外部能力的人。
  • 已经在用 Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
toolscout (Corradocavalli)当前 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Filesystem 560c4363 13 未标注 本地部署 无 2026-05-17
Server Everything (everything) 11 stdio · 本地进程 本地部署 有 2026-05-17
Time 7365cb6d 2 SSE · 服务端推送 远程部署 有 2026-05-18
Everything Claude Code 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Openmemory 557e1585 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

AI代理
字段来自项目仓库与公开索引,中文说明由本站标注
提供方corradocavalli上游标注的维护方 corradocavalli
分类AI代理本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式会话登录远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Python本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

11.5 KB
来自项目仓库与上游目录的原文,未做删改

ToolScout

一种使用MCP(模型上下文协议)服务器进行动态工具发现和执行的智能代理系统,具有向量相似性搜索和对话历史优化功能。

概述

ToolScout是一个基于 微软代理框架 它解决了构建具有广泛功能的AI代理时的两个关键挑战:

  1. 管理大型工具集:随着代理通过MCP服务器访问数十或数百个工具,由于令牌限制和延迟增加,将所有工具加载到代理的上下文中变得不切实际。这也会导致上下文分心和混乱,不相关的工具描述会干扰代理的决策(参见 上下文如何失败).

  2. 长期对话:扩展的多回合交互会积累对话历史,其中不仅包括用户查询和响应,还包括工具调用细节,这些细节会使上下文窗口变得混乱并浪费令牌。

ToolScout通过以下方式应对这些挑战:

  • 向量相似性搜索:动态发现并加载每个查询的3-5个最相关的工具,将工具上下文减少80-90%(50→3.8个平均工具)
  • 智能历史过滤:自动从对话历史记录中删除工具调用和结果消息,仅保留用户查询和助手响应
  • 动态上下文管理:结合这两种优化,使代理能够在扩展对话中与20-30多种工具有效协作,而不会耗尽上下文窗口

这种方法显著减少了令牌的使用(节省了约47%),同时在复杂的多回合对话中保持了完整的功能。

基准测试

模型:GPT-5-Mini。\
场景:场景3(总迭代次数312)

配置 ToolScout+滚动窗口+消息清除 ToolScout+无滚动窗口+信息清除 所有工具+无滚动窗+无消息清除
最大输入令牌数 11332 45672 83307
平均输入令牌 7344 23972 45166
输入令牌总数 2291272 7479400 14091813
平均每转刀具数 3.8 3.8 50
持续时间(分钟) 51 65 76

性能提升

  • 最大输入令牌减少: ~45% (83K → 46K个最大输入令牌)
  • 代币总减少量: ~47% (14M → 7.5M个总输入令牌)
  • 时间缩短: ~14% (76分钟→ 65 最小执行时间)

背景

这项调查的灵感来自Anthropic对高级工具使用模式和基于嵌入的工具搜索的研究:

  • 高级工具使用 -代理系统中优化工具调用的技术
  • 使用嵌入进行工具搜索 -演示基于向量的工具发现的Cookbook示例

特性

  • 🔍 基于矢量的工具发现 使用Azure OpenAI嵌入
  • 🧠 智能对话历史记录 具有自动工具消息过滤功能
  • 🔧 多服务器MCP支持 具有并发服务器连接
  • 📊 优化指标 显示令牌减少和工具选择统计数据
  • 🎯 可配置阈值 相似性和历史限制
  • 🐛 调试模式 用于会话历史检查

构建于

  • 微软代理框架 -代理人工智能应用框架
  • Azure OpenAI -LLM和嵌入模型
  • 快速MCP -模型上下文协议服务器实现
  • 紫外线 -快速Python包管理器

建筑```

┌─────────────────┐
│ User Query │
└────────┬────────┘
│
▼
┌─────────────────────────────┐
│ Vector Similarity Search │ ← Embeddings
│ (Tool Registry) │
└────────┬────────────────────┘
│
▼
┌─────────────────────────────┐
│ Selected Tools (3-5) │
└────────┬────────────────────┘
│
▼
┌─────────────────────────────┐
│ Agent Execution │ ← Filtered History
│ (Azure OpenAI Responses) │
└────────┬────────────────────┘
│
▼
┌─────────────────────────────┐
│ Result + History Update │
└─────────────────────────────┘


## 设置

### 先决条件

- Python 3.13+
- 紫外线 包管理器
- Azure OpenAI访问:
- 聊天模型部署(例如gpt-4o、gpt-4o-mini)
- 嵌入模型部署(例如,text-embedding-3-small)
- 用于身份验证的Azure CLI

### 安装

1. **克隆存储库**```bash
git clone https://github.com/corradocavalli/toolscout.git
cd toolscout
  1. 安装依赖项```bash
    uv sync

3. **配置环境**```bash
cp .env.sample .env
# Edit .env with your Azure OpenAI details
  1. 使用Azure进行身份验证```bash
    az login

### 配置

编辑 `.env` 使用您的设置:```bash
# Azure OpenAI Configuration
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
AGENT_MODEL_DEPLOYMENT_NAME=gpt-4o-mini
AZURE_EMBEDDING_MODEL_DEPLOYMENT_NAME=text-embedding-3-small

# Tool Discovery Settings
TOP_K=3                      # Number of tools to select per query
SIMILARITY_THRESHOLD=0.3     # Minimum similarity score (0-1)

# History Management
MAX_HISTORY_MESSAGES=50      # Maximum messages in conversation history

用法

启动MCP服务器

在单独的终端中:```bash
cd mcp
./start_servers.sh


这将启动3个演示MCP服务器:

- **服务器1** (端口8000):用户管理、电子邮件、天气
- **服务器2** (端口9000):库管理
- **服务器3** (港口10000):股票交易

### 运行交互模式```bash
uv run main.py

使用场景运行```bash

uv run main.py --scenario scenario_1


### 调试模式

查看传递给代理的对话历史记录:```bash
uv run main.py --scenario scenario_1 --debug

禁用优化

将性能与加载的所有工具进行比较:```bash
uv run main.py --scenario scenario_1 --optimize false


## 命令行选项```bash
uv run main.py [OPTIONS]

Options:
--scenario TEXT        Run a scenario file (e.g., scenario_1)
--optimize BOOL        Enable tool selection optimization (default: true)
--debug               Show conversation history in output
--help                Show this message and exit

项目结构```

toolscout/
├── main.py # Main application entry point
├── tool_registry.py # Vector search and tool indexing
├── tool_manager.py # Tool discovery and loading
├── conversation_store.py # Custom history with message filtering and lenght limitation
├── utils.py # Helper functions for display
├── mcp/ # Demo MCP servers
│ ├── server1.py # General tools
│ ├── server2.py # Library management
│ ├── server3.py # Stock trading
│ └── start_servers.sh # Launch all servers
├── scenarios/ # Test scenarios
│ ├── scenario_1.txt # Simple multi-turn
│ ├── scenario_2.txt # Complex interactions
│ └── scenario_3.txt # Extended scenario
└── pyproject.toml # Project dependencies


## 关键概念

### 工具发现

ToolScout使用查询嵌入和工具描述嵌入之间的余弦相似性来选择相关工具:

1. 启动时,所有工具描述都被嵌入并索引
1. 对于每个查询,计算查询嵌入
1. 查找相似度高于阈值的前K个工具
1. 仅将选定的工具加载到代理上下文中

### 历史优化

海关 `LimitedHistoryChatMessageStore` 提供两种操作模式:

**优化模式(默认)**:

- 过滤掉工具调用消息
- 过滤掉工具结果消息
- 仅保留用户查询和助手响应
- 修剪到最后N条消息
- 在典型的多工具场景中,将上下文大小减少约50%

**完整历史记录模式** (`--optimize false`):

- 保留所有对话历史记录,包括工具调用和结果
- 未应用过滤或修剪
- 消耗更多的令牌和上下文空间
- 可用于比较性能或调试工具交互

### 何时使用此方法

当使用时,这种优化策略变得有益 **20~30+工具**低于该阈值,向量相似性搜索和工具选择的开销可能超过减少上下文所节省的令牌。对于较小的工具集(\<20个工具),将所有工具直接加载到代理上下文中通常更简单、更高效。

## 局限性和未来改进

### 刀具选择精度

由于工具选择依赖于语义相似性,因此对于某些查询,某些工具可能无法正确识别。在调整时 `SIMILARITY_THRESHOLD` 参数可以提供帮助,更有效的解决方案涉及两阶段方法:

#### 第一阶段:动作提取

在查询工具注册表之前,使用代理从用户的请求中提取所需的操作:```
User: "If it is raining, book a taxi"
↓
Agent extracts actions: "get_weather, book_taxi"
↓
Registry searches: ["get_weather", "book_transport", "fetch_weather", "book_driver", "book_taxi"]

第二阶段:工具优化

通过让代理基于原始请求从候选工具中进行选择,进一步细化选择:Input: - Original query: "If it is raining, book a taxi" - Candidates: ["get_weather", "book_transport", "fetch_weather", "book_driver", "book_taxi"] ↓ Agent selects: ["get_weather", "book_taxi"]

性能注意事项

这种增强方法的主要挑战是侦察阶段引入的额外延迟:

  • 云LLM:使用小云模型进行大致侦察 双打 总响应时间
  • 本地法学硕士:使用本地模型,如 TinyLlama-1.1B-Chat-v1.0 将开销减少到 15-20%,当需要最大的刀具选择精度时,这可能是可以接受的

推荐:对于大多数用例,当前的向量相似性方法在准确性和延迟之间提供了良好的平衡。仅当工具选择精度至关重要且额外延迟可接受时,才考虑两阶段方法。

替代嵌入模型

当前的实现使用Azure OpenAI的嵌入模型,这需要API调用并产生成本。一个潜在的改进是使用轻量级的本地嵌入模型来评估性能,例如 全迷你LM-L6-v2,这可能:

  • 消除嵌入API的成本和延迟
  • 启用完全脱机操作
  • 提供更快的工具索引和搜索

这将需要基准测试,以确保嵌入质量足以进行准确的工具选择。

对话总结

除了消息过滤和长度限制之外,另一个针对超长对话的优化是实现基于LLM的历史摘要。当对话超过某个阈值(例如,100+条消息)时,LLM可以:

  • 将对话的旧部分总结成简洁的上下文
  • 完整保留最近的消息细节
  • 用摘要替换原始消息以保存令牌

这种方法将能够维护扩展会话的上下文,同时保持令牌使用的可管理性。摘要可以按可配置的时间间隔或消息计数自动触发。

贡献

这是一个示范项目。请随意分叉并适应您的需求!

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
toolscout (Corradocavalli) 怎么安装?

在客户端按下面的安装命令接入:uv run main.py。装完在客户端配置里引用同一个包或端点。

toolscout (Corradocavalli) 怎么在 Claude 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

toolscout (Corradocavalli) 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

toolscout (Corradocavalli) 需要 API Key 吗?

资料标注需要会话登录认证,使用前准备好对应凭据,并按最小权限配置。

toolscout (Corradocavalli) 支持哪些客户端?

资料标注支持 Claude;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

toolscout (Corradocavalli) 能提供哪些能力?

资料显示能力标签包括 工具发现、Python、Claude、上下文管理。具体工具清单以官方文档为准。

toolscout (Corradocavalli) 需要什么运行环境?

运行时为 Python;属于本地进程,需要在本机装好运行环境。

toolscout (Corradocavalli) 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。