金大哥 - run-typescript-skills-mcp MCP 详情

article

README

🚀 运行TypeScript技能MCP服务器

这是一个MCP服务器，它允许AI代理执行TypeScript代码，并能访问~/.claude/skills中的模块化API。

🚀 快速开始

本MCP服务器提供了一个工具：run-skill-code。启用后，你的AI代理可以执行从~/.claude/skills导入并调用函数的TypeScript代码。

✨ 主要特性

适用场景

快速的编程工作流：你的代理无需反复调用命令行工具（速度慢且需进行文本解析），可以直接调用TypeScript函数并获取结构化数据。
更丰富的代理功能：如果你在~/.claude/skills中为任务管理、版本控制工作流、数据处理或其他工具构建了TypeScript API，那么代理可以通过编程方式使用它们。
更好的性能：进程内执行比为每个操作生成新进程要快得多。
类型安全的交互：你的代理可以获得具有正确类型的结构化结果，而不是解析文本输出。

不适用场景

安全风险：代码在进程内执行，具有完整的文件系统访问权限且没有沙箱保护。如果你的代理编写了恶意代码（或出现错误），它将以你的权限运行。
用例有限：仅当你在~/.claude/skills中有（或计划构建）TypeScript API时才有用。如果没有，这个MCP就没有价值。
信任要求：你必须信任你的AI代理能够安全地编写和执行代码，因为没有安全保障。
开发开销：你需要自己构建和维护TypeScript API。

适用情况判断

适合使用的情况：

你在~/.claude/skills中有希望代理使用的TypeScript API。
你信任你的AI代理能够安全地执行代码。
你希望实现快速的编程工作流。
你能接受安全方面的权衡。

不适合使用的情况：

你没有供代理调用的技能/API。
你对进程内代码执行感到不安。
你需要沙箱或安全隔离。
你更喜欢使用命令行工具。

📦 安装指南

前提条件

Bun v1.0.0 或更高版本

安装步骤

git clone <repository-url>
cd run-typescript-skills-mcp
bun install
bun run build

配置MCP客户端

VS Code (.vscode/settings.json)：

{
  "mcp": {
    "servers": {
      "run-typescript-skills": {
        "command": "bun",
        "args": ["/absolute/path/to/run-typescript-skills-mcp/src/mcp-bun.ts"]
      }
    }
  }
}

Claude Desktop：

{
  "mcpServers": {
    "run-typescript-skills": {
      "command": "bun",
      "args": ["/absolute/path/to/run-typescript-skills-mcp/src/mcp-bun.ts"]
    }
  }
}

💻 使用示例

基础用法

启用后，你的代理可以执行如下TypeScript代码：

import { createTask } from '~/.claude/skills/my-workflow/src/api.js';

const task = await createTask({
  title: "Write documentation",
  priority: 1
});

return task;

代理将获得结构化数据：

{
  "returnValue": { "id": "task-123", "title": "Write documentation", "priority": 1 },
  "stdout": "",
  "stderr": ""
}

🔧 技术细节

安全模式

⚠️ 重要提示

无沙箱保护：代码在进程内运行，具有完整的系统访问权限。

与服务器权限相同：如果MCP服务器可以访问某个文件，那么执行的代码也可以。

基于信任：你需要信任你的AI代理编写的是安全代码。

此服务器适用于你信任代理并希望快速、以编程方式访问自己的TypeScript API的受控环境，不适用于执行不受信任的代码、多用户环境或需要隔离的情况。

开发命令

bun run build        # 编译TypeScript
bun run dist         # 构建优化后的捆绑包
bun test             # 运行测试
bun run dev          # 使用MCP检查器的开发模式

架构说明

src/mcp-bun.ts - MCP服务器入口点
src/tools/run-skill-code-mcp.ts - 工具注册
src/tools/run-skill-code.ts - 公共API
src/tools/run-skill-code-impl.ts - 实现

有关架构决策，请参阅 docs/adr/。

📄 许可证

本项目采用MIT许可证，详情请参阅 LICENSE 文件。

run-typescript-skills-mcp