元工具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响应。```bash
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排名:
1. 使用toolsearch标签构建:```bash
go build -tags toolsearch ./cmd/metatools
- 设置环境变量:```bash
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` 连接在构建标签后面,因此服务器保持最小
违约。
通过以下方式在本地启用它:```bash
go get github.com/jonwraymond/toolexec@latest
go run -tags toolruntime ./cmd/metatools
如果你正在开发 toolexec 本地:```bash
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)。
## 快速启动(服务器接线)
最小布线使用适配器层和内部传输包:```go
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 ./...
