@dashclaw/mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DashClaw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# @dashclaw/mcp-server
+
+MCP server for [DashClaw](https://github.com/ucsandman/DashClaw) governance. Exposes 23 governance tools and 4 read-only resources over [Model Context Protocol](https://modelcontextprotocol.io/). Works with Claude Code, Claude Desktop, Claude Managed Agents, and any MCP-compatible client.
+
+## Quick Start
+
+### Claude Desktop / Claude Code (stdio)
+
+```bash
+npx @dashclaw/mcp-server --url https://your-dashclaw.vercel.app --key oc_live_xxx
+```
+
+Or add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "dashclaw": {
+      "command": "npx",
+      "args": ["@dashclaw/mcp-server"],
+      "env": {
+        "DASHCLAW_URL": "https://your-dashclaw.vercel.app",
+        "DASHCLAW_API_KEY": "oc_live_xxx"
+      }
+    }
+  }
+}
+```
+
+### Claude Managed Agents (Streamable HTTP)
+
+If you're running DashClaw, the MCP endpoint is built in at `/api/mcp`:
+
+```python
+agent = client.beta.agents.create(
+    name="Governed Agent",
+    model="claude-sonnet-4-6",
+    tools=[{"type": "agent_toolset_20260401"}],
+    mcp_servers=[{
+        "type": "url",
+        "url": "https://your-dashclaw.vercel.app/api/mcp",
+        "headers": {"x-api-key": "oc_live_xxx"},
+        "name": "dashclaw"
+    }],
+)
+```
+
+## Tools (23)
+
+Grouped by domain. See [`lib/tools.js`](./lib/tools.js) for the canonical definitions.
+
+**Core governance (8)** — the guard / record / invoke loop plus discovery and session lifecycle.
+
+| Tool | Description |
+|---|---|
+| `dashclaw_guard` | Evaluate policies before risky actions |
+| `dashclaw_record` | Log actions to audit trail |
+| `dashclaw_invoke` | Execute governed capabilities (guard + run + record) |
+| `dashclaw_capabilities_list` | Discover available APIs |
+| `dashclaw_policies_list` | See active governance policies |
+| `dashclaw_wait_for_approval` | Block until a human resolves an approval |
+| `dashclaw_session_start` | Register agent session |
+| `dashclaw_session_end` | Close agent session |
+
+**Optimal files (2)** — Code Sessions optimizer output (root CLAUDE.md, path-scoped rules, hooks, skill packs).
+
+| Tool | Description |
+|---|---|
+| `dashclaw_optimal_files_preview` | Preview optimizer output for a session |
+| `dashclaw_optimal_files_manifest` | Generate optimal-files manifest |
+
+**Session continuity (3)** — agent-runtime handoff bundle for the next session.
+
+| Tool | Description |
+|---|---|
+| `dashclaw_handoff_create` | Write handoff bundle for next session |
+| `dashclaw_handoff_latest` | Fetch latest unconsumed handoff |
+| `dashclaw_handoff_consume` | Mark handoff consumed (idempotent) |
+
+**Credential hygiene (3)** — check rotation due-dates before acting on tracked credentials.
+
+| Tool | Description |
+|---|---|
+| `dashclaw_secret_list` | List tracked secrets (metadata only) |
+| `dashclaw_secret_due` | Secrets coming due for rotation |
+| `dashclaw_secret_mark_rotated` | Mark secret rotated (operator-confirmed) |
+
+**Skill safety (1)** — static safety scan of untrusted skill files; results cached by content hash.
+
+| Tool | Description |
+|---|---|
+| `dashclaw_skill_scan` | Scan skill files for unsafe patterns |
+
+**Open loops (3)** — action-scoped commitments ("I will X later" tracker).
+
+| Tool | Description |
+|---|---|
+| `dashclaw_loop_add` | Register action-scoped commitment |
+| `dashclaw_loop_list` | List open/resolved loops |
+| `dashclaw_loop_close` | Resolve an open loop |
+
+**Learning + retrospection (3)** — log and query non-obvious decisions; recent governed-action ledger.
+
+| Tool | Description |
+|---|---|
+| `dashclaw_learning_log` | Log non-obvious decision + outcome |
+| `dashclaw_learning_query` | Query prior decisions/lessons |
+| `dashclaw_decisions_recent` | Recent governed-action ledger |
+
+## Resources (4)
+
+| URI | Description |
+|---|---|
+| `dashclaw://policies` | Active policy set |
+| `dashclaw://capabilities` | Available capabilities and health |
+| `dashclaw://agent/{agent_id}/history` | Recent action history (last 50) |
+| `dashclaw://status` | Instance health + operational metrics |
+
+## Configuration
+
+| CLI Arg | Env Var | Default | Description |
+|---|---|---|---|
+| `--url` | `DASHCLAW_URL` | `http://localhost:3000` | DashClaw instance URL |
+| `--key` | `DASHCLAW_API_KEY` | (empty) | API key (`oc_live_` prefix) |
+| `--agent-id` | `DASHCLAW_AGENT_ID` | (empty) | Default agent ID |
+
+CLI args take precedence over environment variables.

package/bin/dashclaw-mcp.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+import { StdioServerTransport } from '@modelcontextprotocol/server';
+import { createServer } from '../lib/server.js';
+
+process.on('unhandledRejection', (reason) => {
+  console.error('Unhandled Rejection:', reason);
+  process.exit(1);
+});
+
+// Parse CLI args: --url, --key, --agent-id
+const args = process.argv.slice(2);
+const config = {};
+
+for (let i = 0; i < args.length; i++) {
+  switch (args[i]) {
+    case '--url':
+      config.url = args[++i];
+      break;
+    case '--key':
+      config.apiKey = args[++i];
+      break;
+    case '--agent-id':
+      config.agentId = args[++i];
+      break;
+    case '--help':
+      console.error(`Usage: dashclaw-mcp [options]
+
+Options:
+  --url <url>          DashClaw instance URL (default: http://localhost:3000)
+  --key <key>          API key (oc_live_ prefix)
+  --agent-id <id>      Default agent ID
+
+Environment variables (fallback):
+  DASHCLAW_URL         DashClaw instance URL
+  DASHCLAW_API_KEY     API key
+  DASHCLAW_AGENT_ID    Default agent ID`);
+      process.exit(0);
+      break;
+  }
+}
+
+// Env vars as fallback
+config.url = config.url || process.env.DASHCLAW_URL;
+config.apiKey = config.apiKey || process.env.DASHCLAW_API_KEY;
+config.agentId = config.agentId || process.env.DASHCLAW_AGENT_ID;
+
+const server = createServer(config);
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error('@dashclaw/mcp-server running on stdio');

package/lib/client.js

@@ -0,0 +1,102 @@
+/**
+ * HTTP client for DashClaw REST API.
+ * Used by MCP tool and resource handlers.
+ */
+export class DashClawClient {
+  /**
+   * @param {Object} options
+   * @param {string} [options.url] - DashClaw instance URL
+   * @param {string} [options.apiKey] - API key (oc_live_ prefix)
+   * @param {string} [options.agentId] - Default agent ID for tool calls
+   */
+  constructor({ url, apiKey, agentId } = {}) {
+    this.baseUrl = (url || 'http://localhost:3000').replace(/\/$/, '');
+    this.apiKey = apiKey || '';
+    this.agentId = agentId || '';
+  }
+
+  async post(path, body, { timeout = 10000 } = {}) {
+    try {
+      const res = await fetch(`${this.baseUrl}${path}`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'x-api-key': this.apiKey,
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(timeout),
+      });
+      const data = await res.json();
+      if (!res.ok) return { ...data, _status: res.status };
+      return data;
+    } catch (err) {
+      return { error: err.message, _status: 0 };
+    }
+  }
+
+  async get(path, params = {}, { timeout = 10000 } = {}) {
+    const filtered = Object.fromEntries(
+      Object.entries(params).filter(([, v]) => v !== undefined && v !== null && v !== ''),
+    );
+    const qs = new URLSearchParams(filtered).toString();
+    const url = qs ? `${this.baseUrl}${path}?${qs}` : `${this.baseUrl}${path}`;
+    try {
+      const res = await fetch(url, {
+        method: 'GET',
+        headers: { 'x-api-key': this.apiKey },
+        signal: AbortSignal.timeout(timeout),
+      });
+      const data = await res.json();
+      if (!res.ok) return { ...data, _status: res.status };
+      return data;
+    } catch (err) {
+      return { error: err.message, _status: 0 };
+    }
+  }
+
+  async patch(path, body, { timeout = 10000 } = {}) {
+    try {
+      const res = await fetch(`${this.baseUrl}${path}`, {
+        method: 'PATCH',
+        headers: {
+          'Content-Type': 'application/json',
+          'x-api-key': this.apiKey,
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(timeout),
+      });
+      const data = await res.json();
+      if (!res.ok) return { ...data, _status: res.status };
+      return data;
+    } catch (err) {
+      return { error: err.message, _status: 0 };
+    }
+  }
+
+  /**
+   * Low-level fetch passthrough used by toolkit MCP handlers that need
+   * direct access to status codes (e.g., 404-as-null) and per-call methods.
+   * Returns the raw Response-like object: { ok, status, json() }.
+   */
+  async fetch(path, opts = {}) {
+    const method = (opts.method || 'GET').toUpperCase();
+    const headers = { 'x-api-key': this.apiKey, ...(opts.headers || {}) };
+    if (opts.body && !headers['Content-Type']) headers['Content-Type'] = 'application/json';
+    const timeout = opts.timeout ?? 10000;
+    try {
+      const res = await fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers,
+        body: opts.body,
+        signal: AbortSignal.timeout(timeout),
+      });
+      return res;
+    } catch (err) {
+      return {
+        ok: false,
+        status: 0,
+        json: async () => ({ error: err.message, _status: 0 }),
+      };
+    }
+  }
+}

package/lib/resources.js

@@ -0,0 +1,94 @@
+// mcp-server/lib/resources.js
+
+/**
+ * DashClaw MCP resource definitions and handlers.
+ * Resources provide read-only governance context.
+ */
+
+export const RESOURCE_DEFINITIONS = [
+  {
+    uri: 'dashclaw://policies',
+    name: 'DashClaw Policies',
+    description: 'Current active governance policy set for the organization.',
+    mimeType: 'application/json',
+  },
+  {
+    uri: 'dashclaw://capabilities',
+    name: 'DashClaw Capabilities',
+    description: 'Available capabilities and their health status.',
+    mimeType: 'application/json',
+  },
+  {
+    uri: 'dashclaw://agent/{agent_id}/history',
+    name: 'Agent Action History',
+    description: 'Recent action history for a specific agent (last 50 records).',
+    mimeType: 'application/json',
+    isTemplate: true,
+  },
+  {
+    uri: 'dashclaw://status',
+    name: 'DashClaw Status',
+    description: 'Instance health and operational summary metrics.',
+    mimeType: 'application/json',
+  },
+  {
+    uri: 'dashclaw://code-sessions/projects',
+    name: 'Code Sessions Projects',
+    description: 'All Claude Code projects with ingested session data plus per-project rollups.',
+    mimeType: 'application/json',
+  },
+  {
+    uri: 'dashclaw://code-sessions/sessions/{session_id}',
+    name: 'Code Session Detail',
+    description: 'Full detail for one ingested Code Session: session row, messages, tool uses.',
+    mimeType: 'application/json',
+    isTemplate: true,
+  },
+];
+
+/**
+ * Create resource handler functions bound to a DashClawClient instance.
+ * Each handler returns a JSON string of the resource content.
+ * @param {import('./client.js').DashClawClient} client
+ * @returns {Object<string, function>}
+ */
+export function createResourceHandlers(client) {
+  return {
+    'dashclaw://policies': async () => {
+      const result = await client.get('/api/policies', {}, { timeout: 10000 });
+      return JSON.stringify(result);
+    },
+
+    'dashclaw://capabilities': async () => {
+      const result = await client.get('/api/capabilities', {}, { timeout: 10000 });
+      return JSON.stringify(result);
+    },
+
+    'dashclaw://agent/{agent_id}/history': async ({ agent_id }) => {
+      const result = await client.get('/api/actions', {
+        agent_id,
+        limit: '50',
+      }, { timeout: 10000 });
+      return JSON.stringify(result);
+    },
+
+    'dashclaw://status': async () => {
+      const [health, operations] = await Promise.all([
+        client.get('/api/health', {}, { timeout: 10000 }),
+        client.get('/api/operations/summary', {}, { timeout: 10000 }),
+      ]);
+      return JSON.stringify({ health, operations });
+    },
+
+    'dashclaw://code-sessions/projects': async () => {
+      const result = await client.get('/api/code-sessions/projects', {}, { timeout: 15000 });
+      return JSON.stringify(result);
+    },
+
+    'dashclaw://code-sessions/sessions/{session_id}': async ({ session_id }) => {
+      const result = await client.get(`/api/code-sessions/sessions/${encodeURIComponent(session_id)}`,
+        {}, { timeout: 15000 });
+      return JSON.stringify(result);
+    },
+  };
+}