Run Typescript Skills MCP

🚀 Run TypeScript Skills MCP Server

An MCP server that allows AI agents to execute TypeScript code with access to modular APIs in ~/.claude/skills.

🚀 Quick Start

This MCP server offers a single tool: run-skill-code. Once enabled, your AI agent can execute TypeScript code that imports and calls functions from ~/.claude/skills.

✨ Features

Advantages

• Fast programmatic workflows: Instead of your agent repeatedly invoking command-line tools (which is slow and involves text parsing), it can directly call TypeScript functions and receive structured data.
• Richer agent capabilities: If you've developed TypeScript APIs for task management, version control workflows, data processing, or other tooling in ~/.claude/skills, agents can use them programmatically.
• Better performance: In-process execution is significantly faster than spawning processes for each operation.
• Type-safe interactions: Your agent receives structured results with proper types, eliminating the need to parse text output.

Disadvantages

• Security risk: Code executes in-process with full file system access and no sandboxing. If your agent writes malicious code (or makes mistakes), it runs with your permissions.
• Limited use case: This MCP is only valuable if you have (or plan to build) TypeScript APIs in ~/.claude/skills. Otherwise, it offers no value.
• Trust requirement: You must trust your AI agent to write and execute code safely, as there is no safety net.
• Development overhead: You need to build and maintain the TypeScript APIs yourself.

📚 When to Use This

Good Fit

• You have TypeScript APIs in ~/.claude/skills that you want agents to utilize.
• You trust your AI agent to execute code safely.
• You desire fast, programmatic workflows.
• You are comfortable with the security trade-offs.

Not a Good Fit

• You don't have any skills/APIs for the agent to call.
• You are uncomfortable with in-process code execution.
• You require sandboxing or security isolation.
• You prefer using command-line tools.

📦 Installation

Prerequisites

• Bun v1.0.0 or later

Setup

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

Configure Your MCP Client

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"]
    }
  }
}

💻 Usage Examples

Basic Usage

Once enabled, your agent can execute TypeScript code like this:

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

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

return task;

The agent will receive structured data:

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

🔧 Technical Details

Security Model

⚠️ Important Note

• No sandboxing: Code runs in-process with full system access.
• Same permissions as server: If the MCP server can access a file, so can the executed code.
• Trust-based: You're trusting your AI agent to write safe code.

This system is designed for controlled environments where you trust your agent and want fast, programmatic access to your own TypeScript APIs. It is not suitable for executing untrusted code, multi - user environments, or situations requiring isolation.

Development

bun run build        # Compile TypeScript
bun run dist         # Build optimized bundle
bun test             # Run tests
bun run dev          # Development mode with MCP Inspector

Architecture

• src/mcp-bun.ts - MCP server entry point
• src/tools/run-skill-code-mcp.ts - Tool registration
• src/tools/run-skill-code.ts - Public API
• src/tools/run-skill-code-impl.ts - Implementation

See docs/adr/ for architectural decisions.

📄 License

This project is under the MIT License - see LICENSE file for details.

🔗 Links

• Model Context Protocol
• Bun Runtime