norc-mcp 0.0.0-stage → 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Asher Peruscini
+
+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

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# norc-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MCP server for connecting AI platforms (Claude, ChatGPT, etc.) to your [norc](https://norc.app) account — manage cron jobs, machines, and run history from a chat.
+
+## Setup
+
+1. Generate a norc API key: vault → Settings → API Keys → Generate key.
+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 (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:
+
+```bash
+pnpm install
+pnpm build
+PORT=3000 node dist/server.js
+```
+
+Note: self-hosting this server does not mean self-hosting norc itself — it still talks to the hosted norc API.
+
+## Run via Docker
+
+```bash
+docker run -p 3000:3000 norcapp/norc-mcp
+```
+
+Set `NORC_VAULT_URL` if you're pointing at a non-default vault instance:
+
+```bash
+docker run -p 3000:3000 -e NORC_VAULT_URL=https://vault.norc.app norcapp/norc-mcp
+```
+
+## License
+
+MIT

package/dist/server.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { createServer } from 'node:http';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { VaultClient } from './vault-client.js';
+import { registerJobTools } from './tools/jobs.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';
+export function extractApiKey(headers) {
+    const auth = headers.get('authorization') ?? '';
+    if (!auth.startsWith('Bearer '))
+        return null;
+    const raw = auth.slice('Bearer '.length).trim();
+    return raw.startsWith('norc_sk_') ? raw : null;
+}
+function buildServer(apiKey) {
+    const server = new McpServer({ name: 'norc-mcp', version: '0.1.0' });
+    const client = new VaultClient(apiKey, VAULT_BASE_URL);
+    registerJobTools(server, client);
+    registerMachineTools(server, client);
+    registerRunTools(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]}`) {
+    const port = Number(process.env.PORT ?? 3000);
+    createServer(async (req, res) => {
+        if (req.url !== '/mcp' || req.method !== 'POST') {
+            res.writeHead(404).end();
+            return;
+        }
+        const headers = new Headers(req.headers);
+        const apiKey = extractApiKey(headers);
+        if (!apiKey) {
+            res.writeHead(401, { 'content-type': 'application/json' }).end(JSON.stringify({ error: 'missing or malformed norc API key' }));
+            return;
+        }
+        const server = buildServer(apiKey);
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        res.on('close', () => {
+            transport.close();
+            server.close();
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res);
+    }).listen(port, () => {
+        console.log(`norc-mcp listening on :${port}`);
+    });
+}

package/dist/tools/jobs.js

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+export function registerJobTools(server, client) {
+    server.registerTool('list_jobs', {
+        description: "List the user's cron jobs, optionally filtered by machine.",
+        inputSchema: { machine_id: z.string().optional() },
+    }, async ({ machine_id }) => {
+        const params = new URLSearchParams();
+        if (machine_id)
+            params.set('machine_id', machine_id);
+        const qs = params.toString();
+        const path = `/api/v1/jobs${qs ? `?${qs}` : ''}`;
+        const jobs = await client.get(path);
+        return { content: [{ type: 'text', text: JSON.stringify(jobs, null, 2) }] };
+    });
+    server.registerTool('create_job', {
+        description: 'Create a new cron job on a machine.',
+        inputSchema: {
+            machine_id: z.string(),
+            name: z.string(),
+            schedule: z.string().describe('Cron expression, e.g. "0 * * * *"'),
+            command: z.string(),
+            enabled: z.boolean().optional(),
+        },
+    }, async (input) => {
+        const job = await client.post('/api/v1/jobs', input);
+        return { content: [{ type: 'text', text: JSON.stringify(job, null, 2) }] };
+    });
+    server.registerTool('update_job', {
+        description: 'Update an existing job (name, schedule, command, or enabled state).',
+        inputSchema: {
+            id: z.string(),
+            name: z.string().optional(),
+            schedule: z.string().optional(),
+            command: z.string().optional(),
+            enabled: z.boolean().optional(),
+        },
+    }, async ({ id, ...patch }) => {
+        const job = await client.patch(`/api/v1/jobs/${encodeURIComponent(id)}`, patch);
+        return { content: [{ type: 'text', text: JSON.stringify(job, null, 2) }] };
+    });
+    server.registerTool('delete_job', {
+        description: 'Delete a job.',
+        inputSchema: { id: z.string() },
+    }, async ({ id }) => {
+        await client.delete(`/api/v1/jobs/${encodeURIComponent(id)}`);
+        return { content: [{ type: 'text', text: `Deleted job ${id}.` }] };
+    });
+}

package/dist/tools/machines.js

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+export function registerMachineTools(server, client) {
+    server.registerTool('list_machines', { description: "List the user's paired machines.", inputSchema: {} }, async () => {
+        const machines = await client.get('/api/v1/machines');
+        return { content: [{ type: 'text', text: JSON.stringify(machines, null, 2) }] };
+    });
+    server.registerTool('rename_machine', { description: 'Rename a machine.', inputSchema: { id: z.string(), name: z.string() } }, async ({ id, name }) => {
+        const machine = await client.patch(`/api/v1/machines/${encodeURIComponent(id)}`, { name });
+        return { content: [{ type: 'text', text: JSON.stringify(machine, null, 2) }] };
+    });
+    server.registerTool('delete_machine', { description: 'Unpair (delete) a machine.', inputSchema: { id: z.string() } }, async ({ id }) => {
+        await client.delete(`/api/v1/machines/${encodeURIComponent(id)}`);
+        return { content: [{ type: 'text', text: `Unpaired machine ${id}.` }] };
+    });
+}

package/dist/tools/runs.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+export function registerRunTools(server, client) {
+    server.registerTool('list_runs', {
+        description: 'List job run history, optionally filtered by job, machine, or status. Paginated via cursor.',
+        inputSchema: {
+            job_id: z.string().optional(),
+            machine_id: z.string().optional(),
+            status: z.enum(['success', 'warning', 'failed', 'running', 'disabled']).optional(),
+            cursor: z.string().optional(),
+            limit: z.number().int().min(1).max(200).optional(),
+        },
+    }, async (input) => {
+        const params = new URLSearchParams();
+        for (const [k, v] of Object.entries(input)) {
+            if (v !== undefined)
+                params.set(k, String(v));
+        }
+        const qs = params.toString();
+        const result = await client.get(`/api/v1/runs${qs ? `?${qs}` : ''}`);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/vault-client.js

@@ -0,0 +1,47 @@
+export class VaultApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+// Thin HTTP client — every call forwards the end user's own API key as a
+// Bearer token and passes the vault API's error message through verbatim
+// (never swallowed), so a tool caller can explain the real failure.
+export class VaultClient {
+    apiKey;
+    baseUrl;
+    constructor(apiKey, baseUrl = 'https://vault.norc.app') {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+    }
+    async request(method, path, body) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        if (res.status === 204)
+            return undefined;
+        const data = await res.json().catch(() => ({}));
+        if (!res.ok) {
+            throw new VaultApiError(data.error ?? `request failed (${res.status})`, res.status);
+        }
+        return data;
+    }
+    get(path) {
+        return this.request('GET', path);
+    }
+    post(path, body) {
+        return this.request('POST', path, body);
+    }
+    patch(path, body) {
+        return this.request('PATCH', path, body);
+    }
+    delete(path) {
+        return this.request('DELETE', path);
+    }
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "norc-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.2",
+  "description": "MCP server for connecting AI platforms to your norc account — manage cron jobs, machines, and run history.",
+  "type": "module",
+  "license": "MIT",
+  "main": "dist/server.js",
+  "bin": {
+    "norc-mcp": "dist/server.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/norcapp/norc-mcp.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "pnpm@9.15.9",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/server.ts",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5"
+  }
+}