norc-mcp 0.1.0 → 0.3.0

package/README.md

@@ -5,15 +5,55 @@ MCP server for connecting AI platforms (Claude, ChatGPT, etc.) to your [norc](ht
 ## Setup
 
 1. Generate a norc API key: vault → Settings → API Keys → Generate key.
-2. Add this server to your MCP client's connector config, pointing at `https://mcp.norc.app/mcp` with your key as the Bearer token (exact field depends on the client).
+2. Install it for your client (below). Hosted option: point a client that supports remote servers at `https://mcp.norc.app/mcp` with your key as the Bearer token (exact field depends on the client).
+
+## Install
+
+### Claude Desktop
+
+1. Install [Node.js](https://nodejs.org) 20 or newer (Claude Desktop runs the server with `npx`).
+2. Open Claude Desktop → Settings → Developer → Edit Config. This opens `claude_desktop_config.json`:
+   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - Windows: `%APPDATA%\Claude\claude_desktop_config.json` (Microsoft Store install: `%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json`)
+3. Add norc under `mcpServers` (keep any servers already there) and use your own key (vault → Settings → API Keys):
+   ```json
+   {
+     "mcpServers": {
+       "norc": {
+         "command": "npx",
+         "args": ["-y", "norc-mcp"],
+         "env": { "NORC_API_KEY": "norc_sk_..." }
+       }
+     }
+   }
+   ```
+   On Windows, `npx` is a `.cmd` script and may fail to launch directly; use `cmd` instead:
+   ```json
+   "command": "cmd",
+   "args": ["/c", "npx", "-y", "norc-mcp"]
+   ```
+4. Quit Claude Desktop completely and reopen it. Closing the window is not enough. norc's tools then appear in the tools menu.
+
+### Claude Code
+
+Install the [norc plugin](https://github.com/norcapp/norc-claude-plugin), which adds slash commands and starts this server for you, or add it directly:
+
+```
+claude mcp add norc --env NORC_API_KEY=norc_sk_... -- npx -y norc-mcp
+```
+
+### Other local MCP clients (Cursor, etc.)
+
+Use the same `command` / `args` / `env` block as the Claude Desktop config above. Without `NORC_API_KEY` (or `--stdio`) the server starts in HTTP mode instead, and a missing or malformed key in stdio mode exits with an error.
 
 ## Tools
 
 - `list_jobs`, `create_job`, `update_job`, `delete_job`
 - `list_machines`, `rename_machine`, `delete_machine`
 - `list_runs`
+- `sync_jobs` — declarative sync of your full job set (like `norc gitops`). Dry run by default; jobs not listed are deleted when `apply` is true. Needs the gitops sync feature enabled on your account.
 
-## Self-hosting
+## Self-hosting (HTTP)
 
 This server is a thin, stateless client — it holds no secrets and no database access of its own. It only forwards your API key to `vault.norc.app` (or `$NORC_VAULT_URL`). Run your own instance if you'd like:
 

package/dist/server.js

@@ -1,9 +1,13 @@
 #!/usr/bin/env node
+import { realpathSync } from 'node:fs';
 import { createServer } from 'node:http';
+import { pathToFileURL } from 'node:url';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { VaultClient } from './vault-client.js';
 import { registerJobTools } from './tools/jobs.js';
+import { registerGitopsTools } from './tools/gitops.js';
 import { registerMachineTools } from './tools/machines.js';
 import { registerRunTools } from './tools/runs.js';
 const VAULT_BASE_URL = process.env.NORC_VAULT_URL ?? 'https://vault.norc.app';
@@ -15,16 +19,29 @@ export function extractApiKey(headers) {
     return raw.startsWith('norc_sk_') ? raw : null;
 }
 function buildServer(apiKey) {
-    const server = new McpServer({ name: 'norc-mcp', version: '0.1.0' });
+    const server = new McpServer({ name: 'norc-mcp', version: '0.3.0' });
     const client = new VaultClient(apiKey, VAULT_BASE_URL);
     registerJobTools(server, client);
     registerMachineTools(server, client);
     registerRunTools(server, client);
+    registerGitopsTools(server, client);
     return server;
 }
-// Only run the HTTP listener when executed directly, so tests can import
-// extractApiKey/buildServer without binding a port.
-if (import.meta.url === `file://${process.argv[1]}`) {
+// stdio mode (a local MCP client spawns us, key comes from the environment) when
+// NORC_API_KEY is set or --stdio is passed; otherwise the HTTP listener (Docker, self-hosting).
+export function wantsStdio(env, argv) {
+    return argv.includes('--stdio') || Boolean(env.NORC_API_KEY);
+}
+async function runStdio() {
+    const apiKey = process.env.NORC_API_KEY ?? '';
+    if (!apiKey.startsWith('norc_sk_')) {
+        // stdout carries the protocol, so diagnostics go to stderr
+        console.error('norc-mcp: set NORC_API_KEY to a norc API key (norc_sk_...)');
+        process.exit(1);
+    }
+    await buildServer(apiKey).connect(new StdioServerTransport());
+}
+function runHttp() {
     const port = Number(process.env.PORT ?? 3000);
     createServer(async (req, res) => {
         if (req.url !== '/mcp' || req.method !== 'POST') {
@@ -49,3 +66,11 @@ if (import.meta.url === `file://${process.argv[1]}`) {
         console.log(`norc-mcp listening on :${port}`);
     });
 }
+// Only start when executed directly, so tests can import extractApiKey/buildServer without
+// binding a port. realpath: an npm bin is a symlink, so argv[1] differs from import.meta.url.
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+    if (wantsStdio(process.env, process.argv))
+        await runStdio();
+    else
+        runHttp();
+}

package/dist/tools/gitops.js

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+// JSON key, not "a/b": names may contain "/" and would collide.
+const key = (machine, name) => JSON.stringify([machine, name]);
+export function computeDiff(desired, machines, jobs) {
+    const machineName = new Map(machines.map((m) => [m.id, m.name]));
+    const machineId = new Map(machines.map((m) => [m.name, m.id]));
+    const live = new Map(jobs.map((j) => [key(machineName.get(j.machine_id) ?? '', j.name), j]));
+    const want = new Set(desired.map((d) => key(d.machine, d.name)));
+    const errors = [];
+    const creates = [];
+    const updates = [];
+    for (const d of desired) {
+        const k = `${d.machine}/${d.name}`;
+        const mid = machineId.get(d.machine);
+        if (!mid) {
+            errors.push(`${k}: unknown machine "${d.machine}"`);
+            continue;
+        }
+        const existing = live.get(key(d.machine, d.name));
+        if (!existing)
+            creates.push({ key: k, machineId: mid, name: d.name, schedule: d.schedule, command: d.command, enabled: d.enabled });
+        else if (existing.schedule !== d.schedule || existing.command !== d.command || existing.enabled !== d.enabled) {
+            updates.push({ key: k, id: existing.id, patch: { schedule: d.schedule, command: d.command, enabled: d.enabled } });
+        }
+    }
+    const deletes = jobs
+        .filter((j) => !want.has(key(machineName.get(j.machine_id) ?? '', j.name)))
+        .map((j) => ({ key: `${machineName.get(j.machine_id) ?? j.machine_id}/${j.name}`, id: j.id }));
+    return { creates, updates, deletes, errors };
+}
+export function registerGitopsTools(server, client) {
+    server.registerTool('sync_jobs', {
+        description: "Make the account's jobs match a declared set (declarative, like `norc gitops`). Jobs not listed are DELETED. " +
+            'Defaults to a dry run that only returns the diff; set apply=true to execute it. Always show the user the dry-run diff, ' +
+            'especially the deletes, and get their confirmation before applying. Requires the gitops sync feature on the account.',
+        inputSchema: {
+            jobs: z
+                .array(z.object({
+                machine: z.string().describe('Machine name (not id)'),
+                name: z.string(),
+                schedule: z.string().describe('Cron expression, e.g. "0 * * * *"'),
+                command: z.string(),
+                enabled: z.boolean().optional().describe('Defaults to true'),
+            }))
+                .describe('The complete desired job set across all machines'),
+            apply: z.boolean().optional().describe('Execute the diff. Default false (dry run).'),
+        },
+    }, async ({ jobs, apply }) => {
+        const desired = jobs.map((j) => ({ ...j, enabled: j.enabled ?? true }));
+        const [machines, live] = await Promise.all([client.get('/api/v1/machines'), client.get('/api/v1/jobs')]);
+        const { errors, ...diff } = computeDiff(desired, machines, live);
+        if (errors.length > 0) {
+            return { isError: true, content: [{ type: 'text', text: `Not applied. ${errors.join('; ')}` }] };
+        }
+        if (!apply) {
+            return { content: [{ type: 'text', text: JSON.stringify({ applied: false, diff }, null, 2) }] };
+        }
+        const result = await client.post('/api/v1/jobs/sync', diff);
+        return { content: [{ type: 'text', text: JSON.stringify({ applied: true, ...result }, null, 2) }] };
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "norc-mcp",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "MCP server for connecting AI platforms to your norc account — manage cron jobs, machines, and run history.",
   "type": "module",
   "license": "MIT",
@@ -31,13 +31,14 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "zod": "^4.4.3"
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "zod": "^4.6.7"
   },
   "devDependencies": {
-    "typescript": "^5.5.0",
-    "tsx": "^4.0.0",
-    "vitest": "^2.0.0",
-    "@types/node": "^22.0.0"
+    "@types/node": "^22.20.5",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5"
   }
 }