@drumcode/runner 0.1.0

package/README.md

@@ -0,0 +1,139 @@
+# @drumcode/runner
+
+The Drumcode MCP Runner - A local execution engine for AI-Ready SaaS infrastructure.
+
+## Installation
+
+```bash
+# Using npm
+npm install -g @drumcode/runner
+
+# Using pnpm
+pnpm add -g @drumcode/runner
+
+# Or run directly with npx
+npx @drumcode/runner start
+```
+
+## Quick Start
+
+### 1. Configure Claude Desktop
+
+Add Drumcode to your Claude Desktop configuration:
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "drumcode": {
+      "command": "npx",
+      "args": ["@drumcode/runner", "start"],
+      "env": {
+        "DRUMCODE_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+### 2. For Local Development
+
+If you're running from the monorepo:
+
+```json
+{
+  "mcpServers": {
+    "drumcode": {
+      "command": "node",
+      "args": ["/path/to/drumcode/packages/runner/dist/cli.js", "start"],
+      "env": {
+        "DRUMCODE_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+### 3. Restart Claude Desktop
+
+After updating the config, restart Claude Desktop. You should see "drumcode" in the MCP servers list.
+
+## Available Tools
+
+### Core Tools (Always Available)
+
+| Tool | Description |
+|------|-------------|
+| `drumcode_search_tools` | Search for available tools by natural language query |
+| `drumcode_get_tool_schema` | Get detailed schema for a specific tool |
+
+### Full Mode Tools (Only in --mode full)
+
+| Tool | Description |
+|------|-------------|
+| `drumcode_echo` | Echo back input (for testing) |
+| `drumcode_http_get` | Make HTTP GET requests |
+| `arxiv_*` | arXiv search tools (hardcoded) |
+
+### Integration Tools (Via Registry)
+
+When connected to the Drumcode Registry, you can search for and use tools from integrated SaaS platforms like Spotify, Stripe, and more.
+
+## CLI Options
+
+```bash
+drumcode start [options]
+
+Options:
+  -t, --token <token>      Drumcode API token
+  -p, --project <project>  Project name
+  -r, --registry <url>     Registry URL (default: https://api.drumcode.ai)
+  --no-cache               Disable caching
+  -l, --log-level <level>  Log level: debug, info, warn, error (default: info)
+  --transport <type>       Transport type: stdio, sse (default: stdio)
+  -h, --help               Display help
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `DRUMCODE_TOKEN` | API token for Registry authentication |
+| `DRUMCODE_PROJECT` | Project name |
+| `DRUMCODE_REGISTRY_URL` | Custom Registry URL |
+| `DRUMCODE_INTEGRATION_BASE_URLS` | JSON map of integration -> base URL for generic execution |
+| `DRUMCODE_INTEGRATION_HEADERS` | JSON map of integration -> headers for generic execution |
+
+## Security
+
+- **API keys are never sent to the cloud.** All SaaS API keys (Spotify, Stripe, etc.) are loaded from local environment variables and execution happens locally.
+- The Registry only stores tool definitions and metadata, not credentials.
+- Telemetry data is sanitized before transmission (secrets are redacted).
+
+## Development
+
+```bash
+# Build the runner
+pnpm build
+
+# Run in development mode
+pnpm dev
+
+# Test locally
+node dist/cli.js start
+```
+
+## Architecture
+
+The Runner implements the MCP (Model Context Protocol) and acts as a "smart wrapper" that:
+
+1. **Discovers tools** via semantic search against the Drumcode Registry
+2. **Hot-loads schemas** on demand when the LLM needs them
+3. **Executes locally** with zero-trust (your API keys never leave your machine)
+4. **Logs and audits** all actions for compliance
+
+## License
+
+MIT

package/dist/chunk-3CUTJWRW.mjs

@@ -0,0 +1,358 @@
+// src/runner.ts
+import { CORE_TOOLSET, redactSecrets } from "@drumcode/core";
+var DrumcodeRunner = class {
+  options;
+  toolCache = /* @__PURE__ */ new Map();
+  manifestCache = null;
+  constructor(options) {
+    this.options = options;
+    this.log("info", "Drumcode Runner initialized", {
+      registryUrl: options.registryUrl,
+      cacheEnabled: options.cacheEnabled
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Tool Discovery
+  // ---------------------------------------------------------------------------
+  /**
+   * Get the list of tools to expose to the client
+   * Uses Polyfill strategy for non-Anthropic clients
+   */
+  async getToolList(capabilities) {
+    if (capabilities.supportsAdvancedToolUse && capabilities.supportsDeferredLoading) {
+      this.log("debug", "Using Strategy A: Full manifest with deferred loading");
+      return this.getFullManifest();
+    }
+    this.log("debug", "Using Strategy B: Polyfill mode with core toolset");
+    return CORE_TOOLSET;
+  }
+  /**
+   * Fetch the full tool manifest from the Registry
+   */
+  async getFullManifest() {
+    if (this.manifestCache && this.options.cacheEnabled) {
+      return this.manifestCache;
+    }
+    try {
+      const response = await fetch(`${this.options.registryUrl}/v1/manifest`, {
+        headers: this.getAuthHeaders()
+      });
+      if (!response.ok) {
+        throw new Error(`Registry returned ${response.status}`);
+      }
+      const data = await response.json();
+      this.manifestCache = data.tools;
+      return this.manifestCache;
+    } catch (error) {
+      this.log("warn", "Failed to fetch manifest, using cached or fallback", { error });
+      return this.manifestCache || CORE_TOOLSET;
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Tool Execution
+  // ---------------------------------------------------------------------------
+  /**
+   * Execute a tool call
+   */
+  async executeTool(request) {
+    const startTime = Date.now();
+    try {
+      if (request.name === "drumcode_search_tools") {
+        return this.handleSearchTools(request.arguments);
+      }
+      if (request.name === "drumcode_get_tool_schema") {
+        return this.handleGetToolSchema(request.arguments);
+      }
+      return this.executeRegularTool(request);
+    } catch (error) {
+      const latency = Date.now() - startTime;
+      this.log("error", "Tool execution failed", {
+        tool: request.name,
+        error,
+        latencyMs: latency
+      });
+      return {
+        content: [{
+          type: "text",
+          text: `Error executing tool: ${error instanceof Error ? error.message : "Unknown error"}`
+        }],
+        isError: true
+      };
+    }
+  }
+  /**
+   * Handle drumcode_search_tools meta-tool
+   */
+  async handleSearchTools(args) {
+    this.log("debug", "Searching tools", { query: args.query });
+    try {
+      const response = await fetch(`${this.options.registryUrl}/v1/tools/search`, {
+        method: "POST",
+        headers: {
+          ...this.getAuthHeaders(),
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          query: args.query,
+          project_token: this.options.token,
+          limit: 5
+        })
+      });
+      if (!response.ok) {
+        throw new Error(`Search failed with status ${response.status}`);
+      }
+      const data = await response.json();
+      const resultText = data.matches.length > 0 ? data.matches.map(
+        (m, i) => `${i + 1}. **${m.name}** (relevance: ${(m.relevance * 100).toFixed(0)}%)
+   ${m.description}`
+      ).join("\n\n") : "No matching tools found. Try a different search query.";
+      return {
+        content: [{
+          type: "text",
+          text: `Found ${data.matches.length} matching tools:
+
+${resultText}
+
+Use \`drumcode_get_tool_schema\` to get detailed arguments for any of these tools.`
+        }]
+      };
+    } catch (error) {
+      this.log("error", "Search failed", { error });
+      return {
+        content: [{
+          type: "text",
+          text: `Search failed: ${error instanceof Error ? error.message : "Unknown error"}`
+        }],
+        isError: true
+      };
+    }
+  }
+  /**
+   * Handle drumcode_get_tool_schema meta-tool
+   */
+  async handleGetToolSchema(args) {
+    this.log("debug", "Fetching tool schema", { toolName: args.tool_name });
+    if (this.toolCache.has(args.tool_name)) {
+      const cached = this.toolCache.get(args.tool_name);
+      return {
+        content: [{
+          type: "text",
+          text: this.formatToolSchema(cached)
+        }]
+      };
+    }
+    try {
+      const response = await fetch(
+        `${this.options.registryUrl}/v1/tools/${encodeURIComponent(args.tool_name)}`,
+        { headers: this.getAuthHeaders() }
+      );
+      if (!response.ok) {
+        if (response.status === 404) {
+          return {
+            content: [{
+              type: "text",
+              text: `Tool "${args.tool_name}" not found. Use drumcode_search_tools to find available tools.`
+            }],
+            isError: true
+          };
+        }
+        throw new Error(`Failed to fetch schema: ${response.status}`);
+      }
+      const schema = await response.json();
+      const tool = {
+        name: schema.name,
+        description: schema.description,
+        input_schema: schema.input_schema
+      };
+      this.toolCache.set(args.tool_name, tool);
+      return {
+        content: [{
+          type: "text",
+          text: this.formatToolSchema(tool)
+        }]
+      };
+    } catch (error) {
+      this.log("error", "Schema fetch failed", { error });
+      return {
+        content: [{
+          type: "text",
+          text: `Failed to fetch schema: ${error instanceof Error ? error.message : "Unknown error"}`
+        }],
+        isError: true
+      };
+    }
+  }
+  /**
+   * Execute a regular (non-meta) tool
+   */
+  async executeRegularTool(request) {
+    if (request.name === "drumcode_echo") {
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify(request.arguments, null, 2)
+        }]
+      };
+    }
+    if (request.name === "drumcode_http_get") {
+      const url = request.arguments.url;
+      try {
+        const response = await fetch(url);
+        const text = await response.text();
+        return {
+          content: [{
+            type: "text",
+            text: `Status: ${response.status}
+
+${text.slice(0, 5e3)}${text.length > 5e3 ? "...(truncated)" : ""}`
+          }]
+        };
+      } catch (error) {
+        return {
+          content: [{
+            type: "text",
+            text: `HTTP request failed: ${error instanceof Error ? error.message : "Unknown error"}`
+          }],
+          isError: true
+        };
+      }
+    }
+    return {
+      content: [{
+        type: "text",
+        text: `Tool "${request.name}" is not yet implemented. This tool needs to be fetched and executed via the Registry.`
+      }],
+      isError: true
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // Helpers
+  // ---------------------------------------------------------------------------
+  getAuthHeaders() {
+    const headers = {
+      "User-Agent": "drumcode-runner/0.1.0"
+    };
+    if (this.options.token) {
+      headers["Authorization"] = `Bearer ${this.options.token}`;
+    }
+    return headers;
+  }
+  formatToolSchema(tool) {
+    const props = tool.input_schema.properties;
+    const required = tool.input_schema.required || [];
+    const argsDescription = Object.entries(props).map(([name, prop]) => {
+      const req = required.includes(name) ? " (required)" : " (optional)";
+      return `  - ${name}${req}: ${prop.type}${prop.description ? ` - ${prop.description}` : ""}`;
+    }).join("\n");
+    return `## ${tool.name}
+
+${tool.description}
+
+### Arguments:
+${argsDescription || "  No arguments required."}
+
+### Usage:
+Call this tool with the arguments above to execute it.`;
+  }
+  log(level, message, data) {
+    const levels = ["debug", "info", "warn", "error"];
+    const currentLevel = levels.indexOf(this.options.logLevel);
+    const messageLevel = levels.indexOf(level);
+    if (messageLevel >= currentLevel) {
+      const safeData = data ? JSON.parse(redactSecrets(JSON.stringify(data))) : void 0;
+      console.error(`[drumcode] ${message}`, safeData ? safeData : "");
+    }
+  }
+};
+
+// src/server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+async function createServer(options) {
+  const runner = new DrumcodeRunner(options);
+  const server = new Server(
+    {
+      name: "drumcode",
+      version: "0.1.0"
+    },
+    {
+      capabilities: {
+        tools: {}
+      }
+    }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async (request) => {
+    const capabilities = detectClientCapabilities(request);
+    const tools = await runner.getToolList(capabilities);
+    const demoTools = [
+      {
+        name: "drumcode_echo",
+        description: "Echo back the input arguments. Useful for testing.",
+        input_schema: {
+          type: "object",
+          properties: {
+            message: {
+              type: "string",
+              description: "The message to echo back"
+            }
+          },
+          required: ["message"]
+        }
+      },
+      {
+        name: "drumcode_http_get",
+        description: "Make an HTTP GET request to a URL and return the response.",
+        input_schema: {
+          type: "object",
+          properties: {
+            url: {
+              type: "string",
+              description: "The URL to fetch"
+            }
+          },
+          required: ["url"]
+        }
+      }
+    ];
+    const allTools = [...tools, ...demoTools].map((t) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: {
+        type: "object",
+        properties: t.input_schema.properties,
+        required: t.input_schema.required
+      }
+    }));
+    return { tools: allTools };
+  });
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const result = await runner.executeTool({
+      name,
+      arguments: args ?? {}
+    });
+    return {
+      content: result.content,
+      isError: result.isError
+    };
+  });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("[drumcode] MCP Server started");
+}
+function detectClientCapabilities(_request) {
+  return {
+    type: "unknown",
+    supportsAdvancedToolUse: false,
+    supportsDeferredLoading: false
+  };
+}
+
+export {
+  DrumcodeRunner,
+  createServer
+};