@davepi/mcp 1.0.0

package/README.md

@@ -0,0 +1,102 @@
+# @davepi/mcp
+
+One-line MCP wiring for [dAvePi](https://docs.davepi.dev). Connects
+Claude Desktop / Cursor / Claude Code to a dAvePi instance — either
+a remote HTTP `/mcp` endpoint or a local stdio session.
+
+## Install / wire it up
+
+You don't install — `npx -y` runs the latest published version on
+demand.
+
+### Claude Code (`.mcp.json` in the project root)
+
+```json
+{
+  "mcpServers": {
+    "davepi": {
+      "command": "npx",
+      "args": ["-y", "@davepi/mcp"],
+      "env": {
+        "DAVEPI_URL": "http://localhost:5050",
+        "DAVEPI_TOKEN": "<long-lived-jwt>"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+macOS path: `~/Library/Application Support/Claude/claude_desktop_config.json`.
+
+```json
+{
+  "mcpServers": {
+    "davepi": {
+      "command": "npx",
+      "args": ["-y", "@davepi/mcp"],
+      "env": {
+        "DAVEPI_URL": "https://api.example.com",
+        "DAVEPI_TOKEN": "<long-lived-jwt>"
+      }
+    }
+  }
+}
+```
+
+### Cursor (`.cursor/mcp.json` or settings)
+
+```json
+{
+  "mcpServers": {
+    "davepi": {
+      "command": "npx",
+      "args": ["-y", "@davepi/mcp"],
+      "env": {
+        "DAVEPI_URL": "https://api.example.com",
+        "DAVEPI_TOKEN": "<long-lived-jwt>"
+      }
+    }
+  }
+}
+```
+
+## Modes
+
+The wrapper picks one mode based on environment:
+
+| Env vars | Mode | Use when |
+|----------|------|----------|
+| `DAVEPI_URL` + `DAVEPI_TOKEN` | HTTP-proxy | dAvePi is hosted (production deployment, demo instance, etc.) and the agent runs on a developer's laptop. |
+| `DAVEPI_SCHEMAS` (or no env vars in a project with a `schema/versions/` directory) | Local-stdio | dAvePi is installed in the same project as the agent's working tree (`npm install davepi`). The wrapper spawns `davepi mcp` and pipes its stdio. |
+
+Both modes are pure JSON-RPC pumps — neither holds any MCP-protocol
+state, so a future MCP version doesn't require touching this
+package.
+
+## Issuing a long-lived JWT for `DAVEPI_TOKEN`
+
+Run this on the dAvePi server (or anywhere with `TOKEN_KEY`):
+
+```bash
+node -e '
+  const jwt = require("jsonwebtoken");
+  console.log(jwt.sign(
+    { user_id: "<your-user-id>", roles: ["user"] },
+    process.env.TOKEN_KEY,
+    { expiresIn: "30d" }
+  ));
+'
+```
+
+Treat the result like any other API credential.
+
+## Documentation
+
+- [Surfaces → MCP server](https://docs.davepi.dev/surfaces/mcp/) — the full MCP tool surface dAvePi exposes.
+- [Concepts → Why agents come first](https://docs.davepi.dev/concepts/agent-first/) — why MCP is first-class.
+
+## License
+
+ISC. Source: <https://github.com/projik/davepi/tree/main/packages/mcp>.

package/bin/davepi-mcp.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+/**
+ * @davepi/mcp — one-line MCP wiring for a dAvePi instance.
+ *
+ * Two modes, picked by environment:
+ *
+ *   HTTP-proxy (DAVEPI_URL set)
+ *     The wrapper runs as the agent's MCP server (stdio JSON-RPC)
+ *     and forwards every message to the remote dAvePi's /mcp HTTP
+ *     endpoint with `Authorization: Bearer ${DAVEPI_TOKEN}`. Use
+ *     when the dAvePi instance is hosted (demo.davepi.dev,
+ *     production deployment, etc.) and the agent runs on a
+ *     developer's laptop.
+ *
+ *   Local-stdio (DAVEPI_SCHEMAS set, DAVEPI_URL unset)
+ *     The wrapper spawns `davepi mcp` from the project's locally
+ *     installed `davepi` package and pipes its stdio. Use when
+ *     dAvePi is installed in the same project as the agent's
+ *     working tree. This mode requires the project to have
+ *     `davepi` as a dependency; we surface a helpful error if the
+ *     binary can't be found.
+ *
+ * Both modes are pure stdio JSON-RPC pumps — neither holds any
+ * MCP-protocol state of its own, so a future MCP version doesn't
+ * require touching this package.
+ */
+
+'use strict';
+
+const path = require('path');
+
+const HELP = `Usage: davepi-mcp
+
+Pick one mode by environment:
+
+  HTTP-proxy mode:
+    DAVEPI_URL    URL of the dAvePi server (e.g. https://api.example.com)
+    DAVEPI_TOKEN  Long-lived JWT issued by /login on that server
+
+  Local-stdio mode:
+    DAVEPI_SCHEMAS  Path to schema/versions/ (defaults to ./schema/versions)
+
+Examples:
+
+  # Wire an agent to a hosted dAvePi:
+  DAVEPI_URL=https://api.example.com DAVEPI_TOKEN=eyJ... npx -y @davepi/mcp
+
+  # Wire an agent to local schemas (project must have \`davepi\` installed):
+  DAVEPI_SCHEMAS=./schema/versions npx -y @davepi/mcp
+
+Documentation: https://docs.davepi.dev/surfaces/mcp/
+`;
+
+function err(msg) {
+  process.stderr.write(`davepi-mcp: ${msg}\n`);
+}
+
+function help() {
+  process.stderr.write(HELP);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes('--help') || args.includes('-h')) {
+    help();
+    process.exit(0);
+  }
+
+  const url = process.env.DAVEPI_URL;
+  const schemas = process.env.DAVEPI_SCHEMAS;
+
+  if (url) {
+    if (!process.env.DAVEPI_TOKEN) {
+      err('DAVEPI_URL is set but DAVEPI_TOKEN is missing. Set both for HTTP-proxy mode.');
+      help();
+      process.exit(1);
+    }
+    const { runHttpProxy } = require(path.join('..', 'lib', 'http-proxy.js'));
+    return runHttpProxy({
+      url,
+      token: process.env.DAVEPI_TOKEN,
+    });
+  }
+
+  if (schemas || args.length === 0) {
+    // Local-stdio mode. Schemas path defaults to ./schema/versions
+    // (the davepi convention) so a user with a project structured
+    // the standard way can omit DAVEPI_SCHEMAS entirely.
+    const { runLocalStdio } = require(path.join('..', 'lib', 'local-stdio.js'));
+    return runLocalStdio({
+      schemas: schemas || path.join(process.cwd(), 'schema', 'versions'),
+    });
+  }
+
+  help();
+  process.exit(1);
+}
+
+main().catch((e) => {
+  err(e && e.stack ? e.stack : String(e));
+  process.exit(1);
+});

package/lib/http-proxy.js

@@ -0,0 +1,210 @@
+/**
+ * HTTP-proxy mode: bridge stdio JSON-RPC ↔ remote /mcp HTTP endpoint.
+ *
+ * Why a manual stdio loop instead of the MCP SDK's bridge classes:
+ * the MCP protocol is JSON-RPC 2.0 with specific method names. The
+ * wrapper doesn't need to understand any of the methods — it just
+ * forwards bytes — so importing the SDK would add ~MB of code to
+ * pump line-delimited JSON through `fetch`. The dAvePi server's
+ * /mcp endpoint runs StreamableHTTPServerTransport in stateless
+ * mode, which means each POST is one request-response pair with
+ * a JSON body.
+ *
+ * Each line on stdin is one JSON-RPC message from the agent. We
+ * POST it to ${url}/mcp with the bearer token and write the
+ * response body to stdout, terminated by a newline (the SDK's
+ * stdio transport is line-delimited).
+ *
+ * Errors surface to the agent as JSON-RPC error responses so the
+ * agent sees an actionable failure instead of a silent hang. When
+ * the upstream is unreachable we keep the loop alive — the user
+ * may have a transient network blip, and exiting would force the
+ * agent to restart the proxy.
+ */
+
+'use strict';
+
+const readline = require('node:readline');
+
+function buildErrorResponse(reqId, code, message, data) {
+  // JSON-RPC 2.0 error envelope. -32000 to -32099 is the reserved
+  // server-implementation range; we use -32000 for transport errors
+  // so a downstream agent can branch on "talk to operator" vs
+  // "fix your call".
+  return JSON.stringify({
+    jsonrpc: '2.0',
+    id: reqId === undefined ? null : reqId,
+    error: { code, message, ...(data !== undefined ? { data } : {}) },
+  });
+}
+
+// Default upstream timeout. Long enough that a slow aggregation
+// against a remote /mcp doesn't false-positive, short enough that a
+// stalled connection doesn't block the agent indefinitely. Tunable
+// via DAVEPI_HTTP_TIMEOUT_MS for CI / dev / latency-sensitive setups.
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+function getTimeoutMs() {
+  const raw = process.env.DAVEPI_HTTP_TIMEOUT_MS;
+  if (!raw) return DEFAULT_TIMEOUT_MS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_TIMEOUT_MS;
+  return parsed;
+}
+
+async function forwardOne(line, { url, token }) {
+  let parsed;
+  try {
+    parsed = JSON.parse(line);
+  } catch (parseErr) {
+    return buildErrorResponse(null, -32700, `Parse error: ${parseErr.message}`);
+  }
+  const reqId = parsed && Object.prototype.hasOwnProperty.call(parsed, 'id') ? parsed.id : undefined;
+
+  // AbortController guards both phases — the fetch() promise (TCP
+  // connect, headers received) AND response.text() (body streaming).
+  // Without this, a stalled upstream that holds the socket open but
+  // never sends bytes would block the entire stdio loop and every
+  // subsequent message behind it.
+  const timeoutMs = getTimeoutMs();
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    let response;
+    try {
+      response = await fetch(`${url.replace(/\/+$/, '')}/mcp`, {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${token}`,
+          'Content-Type': 'application/json',
+          'Accept': 'application/json, text/event-stream',
+        },
+        body: line,
+        signal: controller.signal,
+      });
+    } catch (fetchErr) {
+      // AbortError surfaces with .name === 'AbortError' on Node 18+;
+      // distinguish it from generic transport errors so the agent
+      // can react differently (a timeout is "retry shortly", a
+      // network error is "operator's broken").
+      if (fetchErr.name === 'AbortError') {
+        return buildErrorResponse(
+          reqId,
+          -32000,
+          `Upstream /mcp timed out after ${timeoutMs}ms`,
+          { timeoutMs }
+        );
+      }
+      return buildErrorResponse(
+        reqId,
+        -32000,
+        `Transport error contacting ${url}: ${fetchErr.message}`
+      );
+    }
+
+    let body;
+    try {
+      body = await response.text();
+    } catch (readErr) {
+      if (readErr.name === 'AbortError') {
+        return buildErrorResponse(
+          reqId,
+          -32000,
+          `Upstream /mcp body read timed out after ${timeoutMs}ms`,
+          { timeoutMs }
+        );
+      }
+      return buildErrorResponse(
+        reqId,
+        -32000,
+        `Transport error reading /mcp body: ${readErr.message}`
+      );
+    }
+
+    if (!response.ok) {
+      return buildErrorResponse(
+        reqId,
+        -32000,
+        `Upstream /mcp returned ${response.status}`,
+        { status: response.status, body: tryParseJson(body) ?? body }
+      );
+    }
+
+    // The MCP HTTP transport (per spec) uses Content-Type to pick
+    // the response shape:
+    //   - application/json — body is the raw JSON-RPC message.
+    //   - text/event-stream — body is one or more SSE events; the
+    //     `data:` field of each event carries the JSON-RPC payload.
+    // The dAvePi server happens to use SSE for typical responses
+    // (the SDK's StreamableHTTPServerTransport sends event: message
+    // frames), so we parse SSE first and fall back to JSON.
+    const contentType = response.headers.get('content-type') || '';
+    if (contentType.includes('text/event-stream')) {
+      const extracted = extractSseData(body);
+      if (extracted) return extracted;
+      // SSE body but no parseable data event — surface as a transport
+      // error rather than dropping the response on the floor.
+      return buildErrorResponse(
+        reqId,
+        -32000,
+        'Upstream /mcp returned SSE with no data frame',
+        { body }
+      );
+    }
+    return body;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Extract the JSON-RPC payload from an SSE response body. Handles the
+ * standard cases (one `event: message` with one `data:` line) and the
+ * spec-permitted multi-line `data:` form (concatenated with newlines).
+ * Returns null when no `data:` field is present.
+ */
+function extractSseData(body) {
+  // Per SSE spec, events are separated by a blank line. Each event
+  // is a sequence of `field: value` lines. We only care about
+  // `data:` for forwarding the JSON-RPC payload upward.
+  const events = body.split(/\r?\n\r?\n/);
+  for (const event of events) {
+    const dataLines = [];
+    for (const line of event.split(/\r?\n/)) {
+      // Spec: `data: <value>` (the leading space is optional). Lines
+      // starting with `:` are comments; everything else is metadata
+      // we ignore for forwarding.
+      if (line.startsWith('data:')) {
+        dataLines.push(line.slice(line.startsWith('data: ') ? 6 : 5));
+      }
+    }
+    if (dataLines.length > 0) {
+      // Multi-line data fields are joined with `\n` per spec.
+      return dataLines.join('\n');
+    }
+  }
+  return null;
+}
+
+function tryParseJson(text) {
+  try { return JSON.parse(text); } catch { return undefined; }
+}
+
+async function runHttpProxy({ url, token }) {
+  if (!url) throw new Error('runHttpProxy: url is required');
+  if (!token) throw new Error('runHttpProxy: token is required');
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    crlfDelay: Infinity,
+  });
+
+  for await (const line of rl) {
+    if (!line.trim()) continue;
+    const out = await forwardOne(line, { url, token });
+    process.stdout.write(out + '\n');
+  }
+}
+
+module.exports = { runHttpProxy, forwardOne, buildErrorResponse, extractSseData };

package/lib/local-stdio.js

@@ -0,0 +1,118 @@
+/**
+ * Local-stdio mode: spawn `davepi mcp` from the user's local install
+ * and pipe stdio through unchanged.
+ *
+ * Why spawn vs in-process: requiring `davepi` directly would boot
+ * Mongo, Apollo, and Express in this process — a lot of side effects
+ * for a wrapper that just brokers stdio. The davepi CLI already does
+ * the right thing in its own process; we just inherit fds.
+ *
+ * Resolution order for the davepi binary:
+ *   1. ./node_modules/.bin/davepi (the project's local install)
+ *   2. PATH (a globally installed davepi)
+ *
+ * If neither resolves, surface a helpful error pointing the user at
+ * `npm install davepi` rather than a cryptic ENOENT.
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const { spawn } = require('child_process');
+
+function findDavepiBin() {
+  // 1. Project-local install. Honour the standard node_modules/.bin
+  //    layout first — that's what the user gets after `npm install
+  //    davepi` in their dAvePi project.
+  const local = path.join(process.cwd(), 'node_modules', '.bin', 'davepi');
+  if (fs.existsSync(local)) return local;
+
+  // Windows ships .cmd shims for the JS launcher; check that too.
+  const localCmd = path.join(process.cwd(), 'node_modules', '.bin', 'davepi.cmd');
+  if (fs.existsSync(localCmd)) return localCmd;
+
+  // 2. Fall back to PATH — a globally installed davepi.
+  return 'davepi';
+}
+
+function runLocalStdio({ schemas } = {}) {
+  const bin = findDavepiBin();
+  const env = { ...process.env };
+  // davepi's bin reads schema/versions from the project root by
+  // default. If the user pointed somewhere non-standard via
+  // DAVEPI_SCHEMAS, propagate it.
+  if (schemas) env.DAVEPI_SCHEMAS = schemas;
+
+  // The returned Promise represents the child's lifecycle:
+  //   - rejects on spawn error (ENOENT, EACCES, ...) so the bin's
+  //     `main().catch()` prints + exits 1.
+  //   - resolves when the child exits normally (the bin then exits
+  //     0). On non-zero exit or signal, we mirror that by exiting
+  //     this process directly — bin shouldn't proceed after the
+  //     subprocess has died.
+  // The previous design called `resolve()` immediately, which
+  // meant any spawn error fired AFTER the bin had already
+  // considered the work done — so `npx -y @davepi/mcp` could exit
+  // 0 even when davepi wasn't installed.
+  return new Promise((resolve, reject) => {
+    const child = spawn(bin, ['mcp'], {
+      stdio: 'inherit',
+      env,
+      // Windows needs shell:true to pick up the .cmd shim if `bin`
+      // is a bare name. Doesn't affect Unix where `bin` is a full path.
+      shell: process.platform === 'win32',
+    });
+
+    let settled = false;
+    const settleReject = (err) => {
+      if (settled) return;
+      settled = true;
+      reject(err);
+    };
+    const settleResolve = () => {
+      if (settled) return;
+      settled = true;
+      resolve();
+    };
+
+    child.on('error', (err) => {
+      if (err.code === 'ENOENT') {
+        process.stderr.write(
+          'davepi-mcp: could not find the `davepi` binary. ' +
+          'Install dAvePi in this project (`npm install davepi`) ' +
+          'and try again, or set DAVEPI_URL to use HTTP-proxy mode.\n'
+        );
+      }
+      settleReject(err);
+    });
+
+    child.on('exit', (code, signal) => {
+      if (signal) {
+        // Re-raise the signal in this process so a parent
+        // supervisor sees the real cause of death.
+        process.kill(process.pid, signal);
+        return;
+      }
+      if (code === 0) {
+        settleResolve();
+        return;
+      }
+      // Non-zero exit — mirror the code so CI / supervisors see
+      // the real outcome. We exit directly because resolving with
+      // a non-zero code wouldn't propagate; the bin doesn't
+      // distinguish between "child failed" and "wrapper failed".
+      process.exit(code ?? 1);
+    });
+
+    // Forward signals to the child so Ctrl-C from the agent cleanly
+    // terminates the davepi server.
+    const forward = (sig) => () => {
+      try { child.kill(sig); } catch (_) { /* already dead */ }
+    };
+    process.on('SIGINT', forward('SIGINT'));
+    process.on('SIGTERM', forward('SIGTERM'));
+  });
+}
+
+module.exports = { runLocalStdio, findDavepiBin };

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@davepi/mcp",
+  "version": "1.0.0",
+  "description": "One-line MCP wiring for dAvePi. Connects Claude Desktop / Cursor / Claude Code to a dAvePi instance — either a remote HTTP /mcp endpoint or a local stdio session.",
+  "license": "ISC",
+  "homepage": "https://docs.davepi.dev/surfaces/mcp/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/projik/davepi.git",
+    "directory": "packages/mcp"
+  },
+  "keywords": [
+    "davepi",
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "cursor",
+    "agent"
+  ],
+  "bin": {
+    "davepi-mcp": "bin/davepi-mcp.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  }
+}