元工具mcp

MCP第一个组成整合工具库的“元工具”服务器:
toolfoundation/model:规范的MCP对齐工具定义和IDtoolfoundation/adapter:协议无关的格式转换tooldiscovery/index:全局注册表+渐进式发现(搜索/命名空间)tooldiscovery/tooldoc:渐进式文档层次+示例tooldiscovery/search:可选搜索策略(例如BM25)toolexec/run:后端无关执行+链接toolexec/code:可选代码样式编排(引擎/运行时支持)toolexec/runtime:建议任何代码执行的沙盒/运行时边界toolops/observe:可选的可观察性中间件toolops/cache:可选缓存中间件
此服务器展示了一个小型的、固执己见的MCP工具界面,用于优化 渐进式披露:
- 廉价地发现工具,
- 那么,只检查你需要的东西
- 以一致的错误语义执行。
MCP工具暴露
发现:
search_tools(便宜,BM25/词汇超过聚合索引)list_tools(分页库存;可按后端过滤)list_namespaces(分页命名空间)
检查:
describe_tool(渐进细节级别)list_tool_exampleslist_toolsets,describe_toolsetlist_skills,describe_skill,plan_skill
执行:
run_tool(发送到本地/提供商/MCP后端)run_chain(使用可选数据传递的顺序工具执行)run_skill(受保护的预注册工作流)execute_code(仅当启用并注入执行器时)
更新日志
看 CHANGELOG.md 发布说明。
运输选择
metatools-mcp支持不同部署场景的多种传输方式:
| 运输 | 命令 | 用例 |
|---|---|---|
stdio | metatools serve | Claude Desktop,本地CLI(默认) |
streamable | metatools serve --transport=streamable --port=8080 | Web应用程序、远程客户端(建议用于HTTP) |
sse | metatools serve --transport=sse --port=8080 | 旧版web客户端(已弃用) |
流式HTTP 通过会话管理实现MCP规范2025-11-25 Mcp-Session-Id header,支持SSE流和JSON响应。
# Basic HTTP server
metatools serve --transport=streamable --port=8080
# With TLS
metatools serve --transport=streamable --port=443 --tls --tls-cert=cert.pem --tls-key=key.pem
# Stateless mode (serverless/FaaS)
metatools serve --transport=streamable --port=8080 --stateless看 docs/usage.md 查看完整配置选项。
搜索策略
默认情况下,元工具mcp使用词汇搜索。对于BM25排名:
- 使用toolsearch标签构建:
go build -tags toolsearch ./cmd/metatools- 设置环境变量:
METATOOLS_SEARCH_STRATEGY=bm25 ./metatools笔记:
- BM25需要
toolsearch构建标签。如果你设置
METATOOLS_SEARCH_STRATEGY=bm25 没有它,服务器现在很快就会发生故障。
METATOOLS_SEARCH_STRATEGY不区分大小写(例如,BM25作品)。
秘密
元工具mcp可以解决 secretref: : 通过启动时的值 toolops/secret 解析器(在严格模式下快速失效)。这是为了 后端URL和HTTP标头值。
Bitwarden Secrets Manager可作为名为 bws 通过 toolops-integrations (使用env变量配置,如 ${BWS_ACCESS_TOKEN} 和 ${BWS_ORG_ID}).
看 docs/usage.md 用于配置示例。
环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
METATOOLS_SEARCH_STRATEGY | lexical | lexical 或 bm25 |
METATOOLS_SEARCH_BM25_NAME_BOOST | 3 | BM25名称字段增强 |
METATOOLS_SEARCH_BM25_NAMESPACE_BOOST | 2 | BM25命名空间字段增强 |
METATOOLS_SEARCH_BM25_TAGS_BOOST | 2 | BM25标签字段增强 |
METATOOLS_SEARCH_BM25_MAX_DOCS | 0 | 要索引的最大文档数(0=无限制) |
METATOOLS_SEARCH_BM25_MAX_DOCTEXT_LEN | 0 | 最大文档文本长度(0=无限制) |
METATOOLS_NOTIFY_TOOL_LIST_CHANGED | true | Emit notifications/tools/list_changed 关于索引更新 |
METATOOLS_NOTIFY_TOOL_LIST_CHANGED_DEBOUNCE_MS | 150 | 取消列表更改通知窗口的抖动 |
传输环境(CLI默认值)
这些应用程序如下 metatools serve 当没有明确设置标志时:
| 变量 | 默认值 | 描述 |
|---|---|---|
METATOOLS_TRANSPORT | stdio | 运输类型: stdio, streamable, sse |
METATOOLS_PORT | 8080 | HTTP端口 streamable/sse |
METATOOLS_HOST | 0.0.0.0 | HTTP绑定主机 |
METATOOLS_CONFIG | “” | 配置文件的路径 |
交通环境(Koanf配置)
这些被消费 config.Load 通过Koanf(文件/env/flags优先):
| 变量 | 默认值 | 描述 |
|---|---|---|
METATOOLS_TRANSPORT_TYPE | stdio | 运输类型: stdio, streamable, sse |
METATOOLS_TRANSPORT_HTTP_HOST | 0.0.0.0 | HTTP绑定主机 |
METATOOLS_TRANSPORT_HTTP_PORT | 8080 | HTTP端口 |
METATOOLS_TRANSPORT_HTTP_TLS_ENABLED | false | 为HTTP传输启用TLS |
METATOOLS_TRANSPORT_HTTP_TLS_CERT | “” | TLS证书路径 |
METATOOLS_TRANSPORT_HTTP_TLS_KEY | “” | TLS密钥路径 |
METATOOLS_TRANSPORT_STREAMABLE_STATELESS | false | 禁用会话管理 |
METATOOLS_TRANSPORT_STREAMABLE_JSON_RESPONSE | false | 更喜欢JSON而不是SSE流 |
METATOOLS_TRANSPORT_STREAMABLE_SESSION_TIMEOUT | 30m | 空闲会话清理持续时间 |
METATOOLS_STATE_RUNTIME_LIMITS_DB | “” | 用于持久执行限制的SQLite文件 |
运行时环境(toolruntime构建标记)
| 变量 | 默认值 | 描述 |
|---|---|---|
METATOOLS_RUNTIME_PROFILE | dev | dev (不安全)或 standard (Docker/WASM) |
METATOOLS_DOCKER_IMAGE | toolruntime-sandbox:latest | 标准配置文件的Docker镜像 |
METATOOLS_WASM_ENABLED | false | 启用WASM后端(wazero) |
METATOOLS_RUNTIME_BACKEND | docker | 首选标准后端: docker 或 wasm |
可选工具exec/运行时集成
execute_code 连接在构建标签后面,因此服务器保持最小 违约。
通过以下方式在本地启用它:
go get github.com/jonwraymond/toolexec@latest
go run -tags toolruntime ./cmd/metatools如果你正在开发 toolexec 本地:
go mod edit -replace github.com/jonwraymond/toolexec=../toolexec
go run -tags toolruntime ./cmd/metatools笔记:
- 构建标签启用
toolexec/runtime-支持toolexec/code.Executor. - 默认配置文件为
dev(不安全的子流程后端)。 - 如果Docker可用,设置
METATOOLS_RUNTIME_PROFILE=standard启用
强化的Docker后端。
- 用以下命令覆盖Docker镜像
METATOOLS_DOCKER_IMAGE(默认值:
toolruntime-sandbox:latest).
- 启用WASM后端
METATOOLS_WASM_ENABLED=true并选择它
随着 METATOOLS_RUNTIME_BACKEND=wasm (使用wazero)。
快速启动(服务器接线)
最小布线使用适配器层和内部传输包:
package main
import (
"context"
"github.com/jonwraymond/metatools-mcp/internal/adapters"
"github.com/jonwraymond/metatools-mcp/internal/server"
"github.com/jonwraymond/metatools-mcp/internal/transport"
"github.com/jonwraymond/tooldiscovery/index"
"github.com/jonwraymond/tooldiscovery/tooldoc"
"github.com/jonwraymond/toolexec/run"
)
func main() {
idx := index.NewInMemoryIndex()
docs := tooldoc.NewInMemoryStore(tooldoc.StoreOptions{Index: idx})
runner := run.NewRunner(run.WithIndex(idx))
cfg := adapters.NewConfig(idx, docs, runner, nil) // executor optional
srv, err := server.New(cfg)
if err != nil {
panic(err)
}
// Use stdio for local/CLI clients
tr := &transport.StdioTransport{}
_ = tr.Serve(context.Background(), srv)
// Or use streamable HTTP for web clients
// tr := &transport.StreamableHTTPTransport{
// Config: transport.StreamableHTTPConfig{Port: 8080},
// }
// _ = tr.Serve(context.Background(), srv)
}请参阅中的完整工作示例(包括本地工具+文档注册) examples/basic/main.go.
它是如何组合在一起的
- MCP表面通过官方SDK实现(
mcp.NewServer,
mcp.AddTool, mcp.CallToolResult{IsError: ...}).
internal/adapters将公共工具库连接到面向处理程序
接口,而不会将协议细节泄露到库中。
- 服务器不会绕过库策略:
- 工具ID来自 toolfoundation/model.Tool.ToolID() - 后端选择如下 tooldiscovery/index.DefaultBackendSelector - 文档上限和模式派生来自 tooldiscovery/tooldoc - 执行/链语义来自 toolexec/run
文档
docs/index.md--概述docs/design-notes.md--权衡和错误语义docs/user-journey.md--端到端代理工作流
版本兼容性
看 VERSIONS.md 对于权威的、自动生成的兼容性矩阵。
持续集成
CI在推送和拉取请求上运行 main 并执行:
go mod downloadgo vet ./...go test ./...
