工具脚本
通过MCP代码模式实现令牌高效工具使用：执行具有完全类型安全的调用MCP工具的TypeScript代码。
Toolscript是一个轻量级的CLI工具和Claude Code插件，使LLM能够编写调用MCP（模型上下文协议）工具的TypeScript代码。它提供自动类型生成、沙盒执行和无缝的Claude代码集成。
特性
- 类型安全MCP访问：从MCP工具模式自动生成TypeScript类型
- 语义工具搜索：使用嵌入+模糊匹配进行工具发现的人工智能搜索
- 沙盒执行：以最小权限保护Deno沙盒
- 工具筛选：只从服务器公开您真正需要的工具
- 克劳德插件：自动网关生命周期管理和挂钩，可自动建议相关技能和工具
我为什么要用这个？
使用MCP工具作为代码而不是直接LLM调用的想法在 Anthropic 和 耀斑. 当前协议实现的主要问题是：
- MCP上下文框： 所有MCP工具及其描述和模式都加载到系统上下文中，占用了宝贵上下文窗口的大量空间，并在每个请求上花费了您的钱。您向代理添加的MCP工具越多，它就越臃肿。
- 工具结果成为上下文： 当LLM将多个工具调用链接在一起以满足更高级的请求时，所有中间工具结果都会传递回模型，为上下文添加更多令牌。来自多个繁重工具调用的大上下文大小可能会使LLM在不同工具调用之间复制数据时更有可能出错。
Toolscript通过以下方式解决了这些问题：
- 仅通过搜索界面向LLM公开所需的工具定义，从而最大限度地减少系统指令的上下文浪费
- 允许工具调用的确定性链接，在调用之间直接传递数据，将LLM处理的输出限制为仅相关结果
该项目的目标是使代理在复杂任务中更具成本效益和准确性。
快速开始
先决条件
Toolscript要求在运行它的计算机上提供以下内容：
安装
可以从以下位置安装和升级Toolscript CLI JSR公司:
deno install --global --allow-net --allow-read --allow-write --allow-env --allow-run --allow-sys --allow-ffi --unstable-webgpu -r -f --name toolscript jsr:@toolscript/cli克劳德代码
要安装匹配的Claude Code插件，请打开 claude 类型：
/plugin marketplace add mKeRix/toolscript
/plugin install toolscript@toolscript最后，重新启动Claude Code以激活插件。
其他代理工具
目前还没有其他代理工具的特殊集成，但作为CLI工具脚本，任何具有shell访问权限的代理都可以使用。 为此，请确保您的计算机上正在运行网关（通过 toolscript gateway start)然后指示您的代理（通过系统提示、插件等）如何查找和使用工具。 你可以从 Claude Code技能定义 这样做。
配置
您可以创建 .toolscript.json 两个级别的文件，用于配置它将加载的服务器，这些文件被合并到将要使用的配置中。如果服务器名称出现在多个文件中，则以最新定义为准。
~/.toolscript.json-您希望在所有正在处理的项目中启用的服务器的用户级配置.toolscript.json-特定于单个存储库或应通过存储库与团队共享的服务器的项目级配置
Toolscript配置格式类似于中的MCP配置 克劳德代码 使工具之间的移植更容易。示例配置可以在下面找到：
{
"mcpServers": {
"filesystem": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
"env": {
"LOG_LEVEL": "debug"
},
"includeTools": ["read_file", "write_file"],
"excludeTools": ["delete_file"]
},
"web-search": {
"type": "http",
"url": "http://localhost:3000",
"headers": {
"Authorization": "Bearer ${SEARCH_API_KEY:-default-key}"
}
},
"github": {
"type": "sse",
"url": "https://api.example.com/github",
"headers": {
"Authorization": "Bearer ${GITHUB_TOKEN}"
}
}
}
}配置文件支持使用环境变量替换 ${VAR} 或 ${VAR:-default} 语法。
配置发生任何更改后，您必须重新启动Claude Code会话才能使其生效。
直接MCP访问与工具脚本访问
建议您在代理配置中保留不需要直接链接的常用工具，这样它就可以在不加载Toolscript的情况下访问这些工具。 一个实际的例子：
- context7-保留在代理配置中，因为输出文本在单次调用后直接由LLM使用，服务器只公开了很少的工具
- atlasian-转向toolscript，因为并非所有工具都需要，LLM可能希望将多个调用链接在一起，服务器会增加MCP上下文的大量膨胀
OAuth2身份验证
Toolscript支持使用授权码流对HTTP和SSE MCP服务器进行OAuth2身份验证。配置了受保护的MCP服务器后，运行：
toolscript auth 这将：
- 执行OAuth发现
- 打开浏览器进行授权
- 将凭据安全地存储在
~/.toolscript/oauth/
你也可以跑步 toolscript auth 没有服务器名称来列出相关服务器及其状态。
建筑
┌─────────────────────┐
│ Toolscript CLI │
└──────────┬──────────┘
│
▼
┌─────────────────────┐ ┌──────────────────┐
│ Gateway Server │◄────►│ MCP Server 1 │
│ (HTTP) │ └──────────────────┘
│ - Type Generation │ ┌──────────────────┐
│ - Tool Aggregation │◄────►│ MCP Server 2 │
│ - /runtime/tools.ts│ └──────────────────┘
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Sandboxed Deno │
│ Subprocess │
│ - Network: Gateway │
│ - No FS access │
└─────────────────────┘决策
还有其他一些很棒的工具与Toolscript有着相似的目标，例如：
不过，这些都没有满足我自己的工作流程和要求，这就是为什么我最终构建了工具脚本。 在开发过程中，我做出了一些有主见的选择，将toolscript与其他工具区分开来：
- 本地Claude代码经验： Toolscript致力于提供一种简单的用户体验，让人感觉像是Claude Code的原生体验。因此，toolscript目前与任何LLM工具兼容，但使用插件、技能和钩子为Claude Code提供了优化的集成。
- CLI而不是元MCP服务器： LLM可以使用shell命令整洁地完成一些工作，例如使用
ghCLI。Toolscript也希望集成到这些工作流中，而不必通过LLM上下文传递结果。因此，它被实现为一个CLI，允许在命令之间传输数据。 - 轻量级Deno沙盒代替Docker： 容器是沙盒代码的好方法，但它们运行起来很重，使容器内代理的使用更加困难。Toolscript利用更轻量级的Deno沙盒来保护LLM。
- 语义工具搜索功能： 一些服务器可以公开许多工具，这些工具在刚刚列出时会占用大量上下文窗口进行筛选。Toolscript实现了语义工具搜索作为主要工作流程，使LLM能够有效地检索它实际要查找的工具定义，而无需遍历所有工具定义。这允许Toolscript扩展到代理中的直接MCP集成之外。
- 技能和工具自动建议： 法学硕士有时很难记住他们正在寻找的工具和技能，尤其是在较长的对话中。Toolscript实现了一个上下文注入钩子，该钩子自动运行LLM的这些步骤，并向其建议相关结果，简化了流程，减少了通常更昂贵的主代理所做的搜索。
发展
# Format code
deno fmt
# Lint code
deno lint
# Run tests
deno task test
# Run CLI
deno task cli
# Install command from source
deno install --global \
--allow-net --allow-read --allow-write --allow-env --allow-run --allow-sys --allow-ffi --unstable-webgpu \
--name toolscript \
--config deno.json \
src/cli/main.ts