@alacrity-ai/kbrelaymcp 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# @alacrity-ai/kbrelaymcp
+
+An [MCP](https://modelcontextprotocol.io) server that gives an agent **kbRelay**
+powers — projects, cards, the timeline, and your @-mentions — over kbRelay's HTTP
+API. It's a thin, standalone stdio client: it carries no privileges of its own, so
+the API token's tenant and **project access (RBAC)** govern exactly what it can see
+and do.
+
+## Install (Claude Code / Claude Desktop)
+
+```bash
+claude mcp add kbrelay --scope user \
+  --env KBRELAY_BASE_URL=https://kbrelay.lalalimited.com \
+  --env KBRELAY_API_KEY=<token from the web "API keys" panel> \
+  -- npx -y @alacrity-ai/kbrelaymcp
+```
+
+`KBRELAY_BASE_URL` can point at the hosted deployment **or** a self-host instance
+(e.g. `http://localhost:8080`), so the same MCP works against both.
+
+### Other MCP clients (Cursor / Windsurf / Cline)
+
+```json
+{
+  "mcpServers": {
+    "kbrelay": {
+      "command": "npx",
+      "args": ["-y", "@alacrity-ai/kbrelaymcp"],
+      "env": {
+        "KBRELAY_BASE_URL": "https://kbrelay.lalalimited.com",
+        "KBRELAY_API_KEY": "<your token>"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+| Env var | Required | Purpose |
+|---|---|---|
+| `KBRELAY_BASE_URL` | yes | kbRelay origin, e.g. `https://kbrelay.lalalimited.com` or `http://localhost:8080`. |
+| `KBRELAY_API_KEY` | yes | A bearer token minted in the web **API keys** panel. Sent as `Authorization: Bearer …`. |
+
+## Tools
+
+| Tool | Kind | What it does |
+|---|---|---|
+| `whoami` | read | The current user + tenant (call first for your user id). |
+| `list_users` | read | Tenant users → resolve names/@handles to ids. |
+| `list_projects` | read | Projects you can access (admins: all). |
+| `get_project` | read | A project + its columns (resolve column ids by name). |
+| `create_project` | write | New project (`code` required, seeds columns). |
+| `list_cards` | read | Cards in a project (filter by column/assignee/q). |
+| `get_card` | read | One card (read the spec before working it). |
+| `create_card` | write | New card (markdown body; `@handle` to notify). |
+| `update_card` | write | Edit and/or **move** (set `columnId` — status = column). |
+| `delete_card` | write | Delete a card (cascades). |
+| `get_timeline` | read | A card's activity log (events + comments). |
+| `add_comment` | write | Report results on the timeline (note or handoff). |
+| `redact_comment` | write | Soft-delete your own comment (leaves a tombstone). |
+| `get_mentions` | read | Your @-mentions — "what did people ask me?". |
+| `mark_mentions_read` | write | Acknowledge mentions after handling them. |
+
+The `get_mentions` + `add_comment` pair makes *"check your mentions and respond to
+them"* a first-class flow.
+
+## Requirements
+
+Node ≥ 20. No configuration files — just the two env vars.
+
+## License
+
+MIT

package/bin/kbrelaymcp.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+// kbRelay MCP — the binary `npx @alacrity-ai/kbrelaymcp` runs. Resolves the
+// compiled stdio entrypoint relative to this shim and starts it. Any failure
+// (missing config, transport error) prints to stderr — stdout is reserved for
+// JSON-RPC — and exits 2.
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+try {
+  const mod = await import(join(here, '..', 'dist', 'transport-stdio.js'));
+  await mod.startStdio();
+} catch (err) {
+  process.stderr.write(`[kbrelaymcp] ${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(2);
+}

package/dist/client.d.ts

@@ -0,0 +1,13 @@
+import type { Config } from './config.js';
+/**
+ * A tiny standalone typed fetch wrapper over kbRelay's HTTP API. Deliberately
+ * NOT a workspace dependency on @kbrelay/shared, so the published package is
+ * self-contained and `npx -y` needs no extra installs. Sends
+ * `Authorization: Bearer <KBRELAY_API_KEY>` (kbRelay's scheme); the token's
+ * tenant + RBAC project access govern exactly what it can see and do.
+ */
+export declare class KbRelayClient {
+    private readonly config;
+    constructor(config: Config);
+    request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
+}

package/dist/client.js

@@ -0,0 +1,56 @@
+/**
+ * A tiny standalone typed fetch wrapper over kbRelay's HTTP API. Deliberately
+ * NOT a workspace dependency on @kbrelay/shared, so the published package is
+ * self-contained and `npx -y` needs no extra installs. Sends
+ * `Authorization: Bearer <KBRELAY_API_KEY>` (kbRelay's scheme); the token's
+ * tenant + RBAC project access govern exactly what it can see and do.
+ */
+export class KbRelayClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async request(method, path, body) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 30_000);
+        try {
+            const res = await fetch(`${this.config.baseUrl}/api${path}`, {
+                method,
+                headers: {
+                    'content-type': 'application/json',
+                    authorization: `Bearer ${this.config.apiKey}`,
+                },
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: controller.signal,
+            });
+            const text = await res.text();
+            let json = null;
+            if (text) {
+                try {
+                    json = JSON.parse(text);
+                }
+                catch {
+                    /* non-JSON body */
+                }
+            }
+            if (!res.ok) {
+                const err = json;
+                let message = err?.error ?? `kbRelay request failed (${res.status})`;
+                if (err?.details) {
+                    message += ` — ${Object.entries(err.details).map(([k, v]) => `${k}: ${v}`).join('; ')}`;
+                }
+                throw new Error(message);
+            }
+            return json;
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'AbortError') {
+                throw new Error('kbRelay request timed out after 30s', { cause: err });
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,12 @@
+/**
+ * MCP config — two env vars, passed via `claude mcp add … --env …`. No TOML /
+ * multi-profile machinery (KISS). Missing either var throws a clear error that
+ * the bin shim prints to stderr before exiting.
+ */
+export interface Config {
+    baseUrl: string;
+    apiKey: string;
+}
+export declare class ConfigError extends Error {
+}
+export declare function loadConfig(env?: NodeJS.ProcessEnv): Config;

package/dist/config.js

@@ -0,0 +1,13 @@
+export class ConfigError extends Error {
+}
+export function loadConfig(env = process.env) {
+    const baseUrl = env.KBRELAY_BASE_URL?.replace(/\/+$/, '');
+    const apiKey = env.KBRELAY_API_KEY;
+    if (!baseUrl) {
+        throw new ConfigError('KBRELAY_BASE_URL is not set — e.g. https://kbrelay.lalalimited.com (or http://localhost:8080 for self-host).');
+    }
+    if (!apiKey) {
+        throw new ConfigError('KBRELAY_API_KEY is not set — mint a token in the kbRelay web "API keys" panel.');
+    }
+    return { baseUrl, apiKey };
+}

package/dist/define-tool.d.ts

@@ -0,0 +1,18 @@
+import type { ZodTypeAny, infer as ZodInfer } from 'zod';
+import type { KbRelayClient } from './client.js';
+/** A tool as declared: a zod input schema + a handler that calls the client. */
+export interface ToolDef<S extends ZodTypeAny> {
+    name: string;
+    /** ≤200 chars; teaches the model kbRelay's conventions. */
+    description: string;
+    inputSchema: S;
+    handler: (args: ZodInfer<S>, client: KbRelayClient) => Promise<unknown>;
+}
+/** A registered tool: JSON Schema for ListTools + a validated runner for CallTool. */
+export interface Tool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    run: (args: unknown, client: KbRelayClient) => Promise<unknown>;
+}
+export declare function defineTool<S extends ZodTypeAny>(def: ToolDef<S>): Tool;

package/dist/define-tool.js

@@ -0,0 +1,15 @@
+import { zodToJsonSchema } from 'zod-to-json-schema';
+export function defineTool(def) {
+    const jsonSchema = zodToJsonSchema(def.inputSchema, {
+        target: 'jsonSchema7',
+        $refStrategy: 'none',
+    });
+    delete jsonSchema.$schema;
+    return {
+        name: def.name,
+        description: def.description,
+        inputSchema: jsonSchema,
+        // async so a zod validation error surfaces as a rejected promise.
+        run: async (args, client) => def.handler(def.inputSchema.parse(args ?? {}), client),
+    };
+}

package/dist/server.d.ts

@@ -0,0 +1,11 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { KbRelayClient } from './client.js';
+/**
+ * The low-level MCP server: advertises `allTools` for ListTools, and for
+ * CallTool finds the tool by name, validates+runs it (zod validation happens
+ * inside the tool's runner), and returns the JSON result as text content
+ * (`isError: true` on failure).
+ */
+export declare function createServer(opts: {
+    client: KbRelayClient;
+}): Server;

package/dist/server.js

@@ -0,0 +1,36 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { allTools } from './tools/index.js';
+/**
+ * The low-level MCP server: advertises `allTools` for ListTools, and for
+ * CallTool finds the tool by name, validates+runs it (zod validation happens
+ * inside the tool's runner), and returns the JSON result as text content
+ * (`isError: true` on failure).
+ */
+export function createServer(opts) {
+    const server = new Server({ name: 'kbrelaymcp', version: '0.1.0' }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, () => ({
+        tools: allTools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const tool = allTools.find((t) => t.name === req.params.name);
+        if (!tool) {
+            return { content: [{ type: 'text', text: `Unknown tool: ${req.params.name}` }], isError: true };
+        }
+        try {
+            const result = await tool.run(req.params.arguments, opts.client);
+            return { content: [{ type: 'text', text: JSON.stringify(result ?? { ok: true }, null, 2) }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: err instanceof Error ? err.message : String(err) }],
+                isError: true,
+            };
+        }
+    });
+    return server;
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,2 @@
+import { type Tool } from '../define-tool.js';
+export declare const allTools: Tool[];

package/dist/tools/index.js

@@ -0,0 +1,161 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+/**
+ * The kbRelay MCP tool surface. Every tool is RBAC-scoped by the token — a tool
+ * only sees/touches projects the token's user can access. Descriptions teach the
+ * model kbRelay's conventions: status = column (move, don't set a field), report
+ * on the timeline (don't rewrite the description), write markdown, `@handle` to
+ * notify, refer to tickets by key (OBL-1).
+ */
+const qs = (params) => {
+    const pairs = Object.entries(params).filter(([, v]) => v != null && v !== '');
+    return pairs.length ? '?' + pairs.map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join('&') : '';
+};
+const enc = encodeURIComponent;
+export const allTools = [
+    // ── Identity ──
+    defineTool({
+        name: 'whoami',
+        description: 'Who this token is: the current user (id, name, kind, role) and tenant. Call first to learn your own user id.',
+        inputSchema: z.object({}),
+        handler: (_a, c) => c.request('GET', '/v1/me'),
+    }),
+    defineTool({
+        name: 'list_users',
+        description: 'List the tenant\'s users (id, name, kind human/agent, @handle). Use to resolve a name to an id for assignment, or a @handle to mention.',
+        inputSchema: z.object({}),
+        handler: (_a, c) => c.request('GET', '/v1/users'),
+    }),
+    // ── Projects ──
+    defineTool({
+        name: 'list_projects',
+        description: 'List projects you can access (admins: all). Each has a code (e.g. OBL) that prefixes its ticket keys.',
+        inputSchema: z.object({ status: z.enum(['active', 'archived']).optional() }),
+        handler: (a, c) => c.request('GET', `/v1/projects${qs({ status: a.status })}`),
+    }),
+    defineTool({
+        name: 'get_project',
+        description: 'Get one project and its columns. Column ids are per-project — always resolve them by name here, never hardcode.',
+        inputSchema: z.object({ projectId: z.string() }),
+        handler: (a, c) => c.request('GET', `/v1/projects/${enc(a.projectId)}`),
+    }),
+    defineTool({
+        name: 'create_project',
+        description: 'Create a project. `code` (2–6 alnum, e.g. LSEO) is required and prefixes ticket keys; default columns are seeded.',
+        inputSchema: z.object({
+            name: z.string(),
+            code: z.string(),
+            description: z.string().nullish(),
+            color: z.string().nullish(),
+        }),
+        handler: (a, c) => c.request('POST', '/v1/projects', a),
+    }),
+    // ── Cards ──
+    defineTool({
+        name: 'list_cards',
+        description: 'List cards in a project. Optional filters: column (id), assignee (user id), q (text search on summary/description).',
+        inputSchema: z.object({
+            projectId: z.string(),
+            column: z.string().optional(),
+            assignee: z.string().optional(),
+            q: z.string().optional(),
+        }),
+        handler: (a, c) => c.request('GET', `/v1/projects/${enc(a.projectId)}/cards${qs({ column: a.column, assignee: a.assignee, q: a.q })}`),
+    }),
+    defineTool({
+        name: 'get_card',
+        description: 'Get one card by id (summary, description, acceptanceCriteria, column, assignee, ticket key). Read the spec before working it.',
+        inputSchema: z.object({ cardId: z.string() }),
+        handler: (a, c) => c.request('GET', `/v1/cards/${enc(a.cardId)}`),
+    }),
+    defineTool({
+        name: 'create_card',
+        description: 'Create a card (defaults to the first column). Write summary plain; description/acceptanceCriteria in markdown; @handle to notify.',
+        inputSchema: z.object({
+            projectId: z.string(),
+            summary: z.string(),
+            description: z.string().nullish(),
+            acceptanceCriteria: z.string().nullish(),
+            columnId: z.string().optional(),
+            assigneeUserId: z.string().nullish(),
+        }),
+        handler: (a, c) => {
+            const { projectId, ...body } = a;
+            return c.request('POST', `/v1/projects/${enc(projectId)}/cards`, body);
+        },
+    }),
+    defineTool({
+        name: 'update_card',
+        description: 'Edit a card AND/OR move it. To change status, set columnId (status = column). Rewrite the spec in place; do NOT log progress here — use add_comment.',
+        inputSchema: z.object({
+            cardId: z.string(),
+            summary: z.string().optional(),
+            description: z.string().nullish(),
+            acceptanceCriteria: z.string().nullish(),
+            columnId: z.string().optional(),
+            assigneeUserId: z.string().nullish(),
+            position: z.number().optional(),
+        }),
+        handler: (a, c) => {
+            const { cardId, ...body } = a;
+            return c.request('PATCH', `/v1/cards/${enc(cardId)}`, body);
+        },
+    }),
+    defineTool({
+        name: 'delete_card',
+        description: 'Delete a card (cascades its timeline + mentions). Irreversible.',
+        inputSchema: z.object({ cardId: z.string() }),
+        handler: (a, c) => c.request('DELETE', `/v1/cards/${enc(a.cardId)}`),
+    }),
+    // ── Timeline ──
+    defineTool({
+        name: 'get_timeline',
+        description: 'The card\'s activity log (system events + comments), oldest→newest — the who-did-what-when history.',
+        inputSchema: z.object({ cardId: z.string() }),
+        handler: (a, c) => c.request('GET', `/v1/cards/${enc(a.cardId)}/timeline`),
+    }),
+    defineTool({
+        name: 'add_comment',
+        description: 'Report results ON the timeline (not by editing the description). A note or a structured handoff. Body is markdown; @handle to notify.',
+        inputSchema: z.object({
+            cardId: z.string(),
+            type: z.enum(['note', 'handoff']).default('note'),
+            body: z.string(),
+            meta: z
+                .object({
+                summary: z.string().optional(),
+                evidence: z.array(z.string()).optional(),
+                verify: z.array(z.string()).optional(),
+                spunOff: z.array(z.string()).optional(),
+            })
+                .optional(),
+        }),
+        handler: (a, c) => {
+            const { cardId, ...body } = a;
+            return c.request('POST', `/v1/cards/${enc(cardId)}/comments`, body);
+        },
+    }),
+    defineTool({
+        name: 'redact_comment',
+        description: 'Redact (soft-delete) YOUR OWN comment — leaves a tombstone. For a leaked secret / PII / wrong-card post. Author-only.',
+        inputSchema: z.object({ cardId: z.string(), commentId: z.string() }),
+        handler: (a, c) => c.request('DELETE', `/v1/cards/${enc(a.cardId)}/comments/${enc(a.commentId)}`),
+    }),
+    // ── Mentions (your inbox) ──
+    defineTool({
+        name: 'get_mentions',
+        description: 'Your @-mentions (default unread). Side-effect-free — listing does NOT clear them. This is how you find "what did people ask me?".',
+        inputSchema: z.object({ status: z.enum(['unread', 'read', 'all']).optional() }),
+        handler: (a, c) => c.request('GET', `/v1/me/mentions${qs({ status: a.status })}`),
+    }),
+    defineTool({
+        name: 'mark_mentions_read',
+        description: 'Acknowledge mentions after handling them: pass mentionIds, or all:true to clear everything.',
+        inputSchema: z
+            .object({ mentionIds: z.array(z.string()).optional(), all: z.boolean().optional() })
+            .refine((v) => v.all || (v.mentionIds && v.mentionIds.length > 0), {
+            message: 'Provide mentionIds or all:true',
+        }),
+        handler: (a, c) => c.request('POST', '/v1/me/mentions/read', a),
+    }),
+];

package/dist/transport-stdio.d.ts

@@ -0,0 +1,7 @@
+/**
+ * stdio entrypoint. Resolves config, logs the active base URL to **stderr**
+ * (stdout is reserved for the JSON-RPC protocol), and connects the server over
+ * stdio. Thrown config errors propagate to the bin shim, which prints them and
+ * exits 2.
+ */
+export declare function startStdio(): Promise<void>;

package/dist/transport-stdio.js

@@ -0,0 +1,17 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { loadConfig } from './config.js';
+import { KbRelayClient } from './client.js';
+import { createServer } from './server.js';
+/**
+ * stdio entrypoint. Resolves config, logs the active base URL to **stderr**
+ * (stdout is reserved for the JSON-RPC protocol), and connects the server over
+ * stdio. Thrown config errors propagate to the bin shim, which prints them and
+ * exits 2.
+ */
+export async function startStdio() {
+    const config = loadConfig();
+    process.stderr.write(`[kbrelaymcp] kbRelay MCP server → ${config.baseUrl}\n`);
+    const client = new KbRelayClient(config);
+    const server = createServer({ client });
+    await server.connect(new StdioServerTransport());
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@alacrity-ai/kbrelaymcp",
+  "version": "0.1.0",
+  "description": "MCP server for kbRelay — give an agent kanban powers (projects, cards, timeline, mentions) over the kbRelay API.",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "bin": {
+    "kbrelaymcp": "./bin/kbrelaymcp.mjs"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit -p tsconfig.build.json",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "kbrelay",
+    "kanban",
+    "agents"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.1",
+    "zod-to-json-schema": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "~5.9.3",
+    "vitest": "^2.1.0"
+  }
+}