scc-mcp 0.1.0

package/README.md

@@ -0,0 +1,67 @@
+# scc-mcp
+
+A stdio [MCP](https://modelcontextprotocol.io) server that bridges the
+Scarborough Community Choir API into any MCP client (Claude Desktop, etc.).
+
+Everything the AI can do is defined **server-side** in the API's `/ai/manifest`
+endpoint and only handed to a valid API key. This package ships no knowledge of
+the API surface itself — it's a generic manifest→REST bridge.
+
+## 1. Get an API key
+
+Sign in to the admin, open the **AI Access** page, and generate a key. Choose a
+read-only or read/write scope as appropriate. Copy the key — it's shown once.
+
+## 2. Install into Claude Desktop
+
+The interactive installer locates Claude Desktop's config, asks for the API URL
+and your key, and merges in an `scc` server (keeping any servers you already
+have):
+
+```sh
+npx scc-mcp install
+```
+
+Then **fully quit and reopen Claude Desktop**. The choir tools appear once it
+reconnects.
+
+### Manual setup
+
+Alternatively, edit Claude Desktop's config yourself:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+Add an `scc` entry under `mcpServers` (create the file/object if missing):
+
+```json
+{
+  "mcpServers": {
+    "scc": {
+      "command": "npx",
+      "args": ["-y", "scc-mcp"],
+      "env": {
+        "SCC_API_URL": "http://localhost:3200",
+        "SCC_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving.
+
+## Configuration
+
+| Variable      | Default                 | Description                          |
+| ------------- | ----------------------- | ------------------------------------ |
+| `SCC_API_KEY` | _(required)_            | Key from the admin AI Access page.   |
+| `SCC_API_URL` | `http://localhost:3200` | Base URL of the choir API.           |
+
+Running the server with `SCC_API_KEY` unset prints a help message and exits
+non-zero.
+
+## Bin
+
+- `scc-mcp` — the MCP server (run over stdio by the client).
+  Run `scc-mcp install` to launch the interactive Claude Desktop installer instead.

package/dist/client.js

@@ -0,0 +1,53 @@
+/**
+ * Thin HTTP client over the Scarborough Community Choir REST API. Every request
+ * carries the AI's API key, so the server applies the owning user's roles and
+ * read-only scope — this client never makes authorization decisions itself.
+ */
+export class ApiClient {
+    baseUrl;
+    apiKey;
+    userAgent;
+    constructor(baseUrl, apiKey, version) {
+        // Normalise so `baseUrl + path` never doubles or drops a slash.
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+        this.apiKey = apiKey;
+        this.userAgent = `scc-mcp/${version}`;
+    }
+    async request(method, path, opts = {}) {
+        const url = new URL(this.baseUrl + (path.startsWith("/") ? path : `/${path}`));
+        if (opts.query) {
+            for (const [k, v] of Object.entries(opts.query)) {
+                if (v !== undefined && v !== null && v !== "")
+                    url.searchParams.set(k, String(v));
+            }
+        }
+        const headers = {
+            "X-Api-Key": this.apiKey,
+            Accept: "application/json",
+            "User-Agent": this.userAgent,
+        };
+        let body;
+        // GET never carries a body; every other method (incl. DELETE, e.g.
+        // /tags/assign) may, so send it whenever one was provided.
+        if (opts.body !== undefined && method !== "GET") {
+            headers["Content-Type"] = "application/json";
+            body = JSON.stringify(opts.body);
+        }
+        const res = await fetch(url, { method, headers, body });
+        const contentType = res.headers.get("content-type") ?? "";
+        if (contentType.includes("application/json")) {
+            return { ok: res.ok, status: res.status, data: await res.json(), contentType };
+        }
+        if (contentType.startsWith("text/") || contentType.includes("charset")) {
+            return { ok: res.ok, status: res.status, text: await res.text(), contentType };
+        }
+        // Binary (PDF / ZIP / image): don't pull bytes into the model context.
+        const buf = await res.arrayBuffer();
+        return {
+            ok: res.ok,
+            status: res.status,
+            text: `<binary ${contentType || "response"}, ${buf.byteLength} bytes — not returned; download via the web app>`,
+            contentType,
+        };
+    }
+}

package/dist/dispatch.js

@@ -0,0 +1,78 @@
+/** Resolve {placeholders} in the path and return the args not consumed by it. */
+function fillPath(template, args) {
+    const used = new Set();
+    const path = template.replace(/\{(\w+)\}/g, (_m, key) => {
+        used.add(key);
+        return encodeURIComponent(String(args[key] ?? ""));
+    });
+    const rest = {};
+    for (const [k, v] of Object.entries(args))
+        if (!used.has(k))
+            rest[k] = v;
+    return { path, rest };
+}
+/** Build the body for an `in: "body"` tool, honouring `spread` and keeping nulls. */
+function buildBody(rest, spread) {
+    const out = {};
+    for (const [k, v] of Object.entries(rest)) {
+        if (k === spread)
+            continue;
+        if (v !== undefined)
+            out[k] = v; // keep null — it can be meaningful (e.g. unassign)
+    }
+    if (spread) {
+        const extra = rest[spread];
+        if (extra && typeof extra === "object")
+            Object.assign(out, extra);
+    }
+    return out;
+}
+function buildRequest(exec, args) {
+    // api_request — method/path/query/body come straight from the args.
+    if (exec.mode === "passthrough") {
+        return {
+            method: String(args.method ?? "GET"),
+            path: String(args.path ?? "/"),
+            query: args.query,
+            body: args.body,
+        };
+    }
+    const { path, rest } = fillPath(exec.path, args);
+    const req = { method: exec.method, path };
+    if (exec.bodyFrom) {
+        req.body = args[exec.bodyFrom]; // the whole body is one arg (e.g. an update's `fields`)
+    }
+    else if (exec.in === "body") {
+        req.body = buildBody(rest, exec.spread);
+    }
+    else if (exec.in === "query") {
+        const query = {};
+        for (const [k, v] of Object.entries(rest))
+            if (v !== undefined)
+                query[k] = v;
+        req.query = query;
+    }
+    return req;
+}
+export async function execute(client, exec, args) {
+    const { method, path, query, body } = buildRequest(exec, args);
+    return client.request(method, path, { query, body });
+}
+/** Format an API result as MCP tool-call content. */
+export function toContent(r) {
+    const payload = r.data !== undefined ? r.data : (r.text ?? "");
+    const text = typeof payload === "string" ? payload : JSON.stringify(payload, null, 2);
+    if (r.ok)
+        return { content: [{ type: "text", text }] };
+    const hint = r.status === 401
+        ? "(The API key is missing, invalid, or revoked.)"
+        : r.status === 403
+            ? "(The key's user lacks permission for this, or it is a read-only key being used for a write.)"
+            : "";
+    return {
+        isError: true,
+        content: [
+            { type: "text", text: `Request failed — HTTP ${r.status}.\n${text}\n\n${hint}` },
+        ],
+    };
+}

package/dist/index.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { ApiClient } from "./client.js";
+import { execute, toContent } from "./dispatch.js";
+// `scc-mcp install` runs the Claude Desktop installer; with no subcommand we
+// start the MCP server below. A single bin keeps `npx scc-mcp [install]`
+// unambiguous (npx can't choose between multiple bins).
+if (process.argv[2] === "install") {
+    const { runInstaller } = await import("./install.js");
+    await runInstaller().catch((err) => {
+        console.error(`\n[scc-mcp] ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    });
+    process.exit(0);
+}
+const VERSION = "0.1.0";
+const API_URL = process.env.SCC_API_URL ?? "http://localhost:3200";
+const API_KEY = process.env.SCC_API_KEY ?? "";
+if (!API_KEY) {
+    // stderr, not stdout — stdout is the MCP protocol channel.
+    console.error("[scc-mcp] Missing SCC_API_KEY. Generate a key in the admin under AI Access,\n" +
+        "then set SCC_API_KEY (and optionally SCC_API_URL, default http://localhost:3200).");
+    process.exit(1);
+}
+const client = new ApiClient(API_URL, API_KEY, VERSION);
+// The package knows exactly one endpoint. Everything the AI can do is defined
+// server-side and only handed to a valid API key — so nothing about the API
+// surface ships in this (publishable) package.
+const res = await client.request("GET", "/ai/manifest");
+if (!res.ok || !res.data || typeof res.data !== "object") {
+    const hint = res.status === 401
+        ? "the API key is missing, invalid, or revoked."
+        : res.status === 404
+            ? `the API at ${API_URL} doesn't expose /ai/manifest — update it to a version with MCP support.`
+            : `HTTP ${res.status} from ${API_URL}/ai/manifest.`;
+    console.error(`[scc-mcp] Could not load the tool manifest: ${hint}`);
+    process.exit(1);
+}
+const manifest = res.data;
+const byName = new Map(manifest.tools.map((t) => [t.name, t]));
+const server = new Server({ name: "scarborough-community-choir", version: VERSION }, { capabilities: { tools: {} }, instructions: manifest.instructions });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: manifest.tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        // Manifest carries JSON Schema directly (built server-side from zod).
+        inputSchema: t.inputSchema,
+        ...(t.annotations ? { annotations: t.annotations } : {}),
+    })),
+}));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const tool = byName.get(req.params.name);
+    if (!tool) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: `Unknown tool: ${req.params.name}` }],
+        };
+    }
+    const args = (req.params.arguments ?? {});
+    return toContent(await execute(client, tool.exec, args));
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`[scc-mcp] connected — API ${API_URL} · ${manifest.tools.length} tools (manifest v${manifest.version})`);

package/dist/install.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+/**
+ * Interactive installer for the Scarborough Community Choir MCP server.
+ *
+ * It locates the Claude Desktop config, prompts for the API URL + key, merges
+ * an `scc` entry into `mcpServers` (preserving any existing servers), and writes
+ * it back with a backup. Only the Node standard library is used.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline";
+const DEFAULT_API_URL = "http://localhost:3200";
+/** Locate Claude Desktop's config file for the current platform. */
+function configPath() {
+    const home = homedir();
+    switch (platform()) {
+        case "darwin":
+            return join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+        case "win32":
+            return join(process.env.APPDATA ?? join(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+        default:
+            // Linux / other — Claude Desktop isn't officially shipped here, but
+            // follow the same XDG-ish convention so the file is at least sensible.
+            return join(process.env.XDG_CONFIG_HOME ?? join(home, ".config"), "Claude", "claude_desktop_config.json");
+    }
+}
+/** Read + parse the config, tolerating a missing or empty file. Returns {} when absent. */
+function readConfig(path) {
+    if (!existsSync(path))
+        return {};
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8").trim();
+    }
+    catch (err) {
+        throw new Error(`Could not read ${path}: ${err.message}`);
+    }
+    if (raw === "")
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+            return parsed;
+        throw new Error("config is not a JSON object");
+    }
+    catch (err) {
+        throw new Error(`The existing config at ${path} is not valid JSON (${err.message}).\nFix or remove it, then re-run the installer.`);
+    }
+}
+/**
+ * Ask a question. Resolves `null` if the input stream closes (EOF) before an
+ * answer is given. We consume `line`/`close` events directly rather than via
+ * `rl.question`'s callback so that, when stdin is a pipe and both a buffered
+ * line and `close` are queued together, the line always wins — `rl.question`
+ * alone races and can drop the final line (or hang on a closed pipe).
+ */
+/**
+ * A line-at-a-time prompter built on a *persistent* `line` listener feeding a
+ * queue. A per-question listener loses lines a buffered pipe emits back-to-back
+ * (and `rl.question` races `line` vs `close` on a closed pipe); buffering avoids
+ * both. `ask` resolves the next queued line, or `null` once input is exhausted.
+ */
+function makePrompter(rl, out) {
+    const lines = [];
+    let waiting = null;
+    let closed = false;
+    const deliver = () => {
+        if (!waiting)
+            return;
+        if (lines.length > 0) {
+            const resolve = waiting;
+            waiting = null;
+            resolve(lines.shift());
+        }
+        else if (closed) {
+            const resolve = waiting;
+            waiting = null;
+            resolve(null);
+        }
+    };
+    rl.on("line", (line) => {
+        lines.push(line.trim());
+        deliver();
+    });
+    rl.once("close", () => {
+        closed = true;
+        // Let any already-queued `line` events settle first, then flush EOF.
+        setImmediate(deliver);
+    });
+    return {
+        get closed() {
+            return closed && lines.length === 0;
+        },
+        ask(question) {
+            out.write(question);
+            if (lines.length > 0)
+                return Promise.resolve(lines.shift());
+            if (closed)
+                return Promise.resolve(null);
+            return new Promise((resolve) => {
+                waiting = resolve;
+            });
+        },
+    };
+}
+export async function runInstaller() {
+    const path = configPath();
+    console.log("Scarborough Community Choir — Claude Desktop MCP installer\n");
+    console.log(`Config file: ${path}\n`);
+    // Read first so a malformed existing file aborts before we prompt.
+    const config = readConfig(path);
+    const out = process.stdout;
+    // No `output` on the interface: prompts are written via the prompter so the
+    // answer arrives on the buffered `line` queue. `terminal: false` keeps
+    // readline from echoing or rewriting lines.
+    const rl = createInterface({ input: process.stdin, terminal: false });
+    const prompter = makePrompter(rl, out);
+    try {
+        const urlAnswer = await prompter.ask(`SCC API URL [${DEFAULT_API_URL}]: `);
+        const apiUrl = urlAnswer?.trim() || DEFAULT_API_URL;
+        let apiKey = "";
+        // Re-prompt while empty, but stop if the input stream is exhausted (EOF) —
+        // otherwise we'd loop forever with no way to answer.
+        while (!apiKey && !prompter.closed) {
+            const answer = await prompter.ask("SCC_API_KEY (from the admin → AI Access page): ");
+            apiKey = (answer ?? "").trim();
+            if (!apiKey && !prompter.closed) {
+                out.write("  An API key is required. Generate one in the admin under AI Access.\n");
+            }
+        }
+        if (!apiKey) {
+            throw new Error("No API key was provided. Re-run and paste a key from the admin AI Access page.");
+        }
+        config.mcpServers ??= {};
+        const servers = config.mcpServers;
+        if (servers.scc) {
+            console.log("\nAn existing 'scc' MCP server entry was found and will be replaced.");
+        }
+        servers.scc = {
+            command: "npx",
+            args: ["-y", "scc-mcp"],
+            env: { SCC_API_URL: apiUrl, SCC_API_KEY: apiKey },
+        };
+        // Back up any existing file before overwriting.
+        if (existsSync(path)) {
+            const backup = `${path}.bak`;
+            try {
+                writeFileSync(backup, readFileSync(path));
+                console.log(`\nBacked up existing config to ${backup}`);
+            }
+            catch (err) {
+                console.warn(`  Warning: could not write backup (${err.message}).`);
+            }
+        }
+        else {
+            mkdirSync(dirname(path), { recursive: true });
+        }
+        writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+        console.log("\nDone. The 'scc' MCP server is configured.\n");
+        console.log("Next steps:");
+        console.log("  1. Fully quit Claude Desktop (Cmd+Q on macOS), then reopen it.");
+        console.log("  2. The choir tools will appear once it reconnects.");
+        console.log(`\n  API URL: ${apiUrl}`);
+    }
+    finally {
+        rl.close();
+    }
+}
+// Invoked via the `scc-mcp install` subcommand (see index.ts), not run directly.

package/package.json

@@ -0,0 +1,35 @@
+{
+	"name": "scc-mcp",
+	"version": "0.1.0",
+	"type": "module",
+	"description": "Key-based MCP server exposing the Scarborough Community Choir API so an AI can query data and act like an assistant.",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/AccentDesign/ScarboroughCommunityChoir-Hono-Astro.git",
+		"directory": "apps/mcp"
+	},
+	"bin": {
+		"scc-mcp": "./dist/index.js"
+	},
+	"main": "./dist/index.js",
+	"files": ["dist", "README.md"],
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"dev": "tsx src/index.ts",
+		"start": "node dist/index.js",
+		"install:claude": "node dist/index.js install",
+		"build": "tsc",
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.29.0",
+		"zod": "^3.24.0"
+	},
+	"devDependencies": {
+		"@types/node": "^22.0.0",
+		"tsx": "^4.21.0",
+		"typescript": "^5.7.0"
+	}
+}