@miadi/connector 0.0.0-stage → 0.1.0

package/dist/server.d.ts

@@ -0,0 +1,18 @@
+import { MiadiOAuthProvider } from "./oauth.js";
+import type { MiadiPerson } from "./people.js";
+import { Ledger } from "./store.js";
+import type { ConnectorRecord } from "./records.js";
+import type { ConnectorConfig } from "./config.js";
+export interface ConnectorDeps {
+    identify: (token: string) => Promise<MiadiPerson | null>;
+    fetchImpl?: typeof fetch;
+    /** The factory directory holding queue/ (default ~/.miadi/factory). */
+    factoryDir?: string;
+    tmuxSessions?: () => string[];
+}
+export declare function createConnectorApp(config: ConnectorConfig, deps: ConnectorDeps): {
+    app: import("express-serve-static-core").Express;
+    provider: MiadiOAuthProvider;
+    ledger: Ledger<ConnectorRecord>;
+};
+export declare const INSTRUCTIONS = "Miadi is a relational software factory: agent sessions, Miadi reviews of screenwalks, Chronicle episodes, talking circles and the five accountable circles (Story, Stewardship, Engineering, Evaluation, Continuity) across three domains (Creative, Ceremonial, Engineering).\n\nStart with get_capabilities: it says who you are signed in as, which tools are live, and which return not_implemented.\n\nRules every tool keeps:\n- Every record names the person who made it, with a claim category: observed, hypothesis, desired_future, fiction or verified_implementation. Keep fiction and desired futures apart from what was observed.\n- Requests (runs, review operations, Deep Diver, review-to-episode links, session completion, calendar events) are recorded as awaiting_approval. Nothing runs, publishes or closes until a person approves it in Miadi.\n- An unknown id is answered as not found, never invented. A missing backing service is answered as unavailable.\n- Use the miadi-review:<uuid>, miadi-chronicle://<n>, owner/repo#n and session:<uuid> reference forms.";

package/dist/server.js

@@ -0,0 +1,104 @@
+/**
+ * The connector's HTTP surface:
+ *
+ *   /.well-known/oauth-*        OAuth discovery (MCP authorization spec)
+ *   /authorize /token /register /revoke, /authorize/confirm   sign-in
+ *   /mcp                        the MCP endpoint (streamable HTTP, stateless)
+ *   /health                     liveness, no data
+ *
+ * Every MCP request carries the signed-in person, and each tool call runs
+ * as that person (see tools.ts).
+ */
+import express from "express";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { mcpAuthRouter, getOAuthProtectedResourceMetadataUrl } from "@modelcontextprotocol/sdk/server/auth/router.js";
+import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
+import { MiadiOAuthProvider, SCOPES, emptyOAuthState } from "./oauth.js";
+import { registerApprovalRoutes } from "./approve.js";
+import { JsonFile, Ledger, ensureStateDir, statePaths } from "./store.js";
+import { registerTools } from "./tools.js";
+import { MiadiClient } from "./miadi.js";
+import { ReviewClient } from "./reviews.js";
+import { VERSION } from "./version.js";
+export function createConnectorApp(config, deps) {
+    ensureStateDir(config.stateDir);
+    const paths = statePaths(config.stateDir);
+    const oauthState = new JsonFile(paths.oauth, emptyOAuthState);
+    const ledger = new Ledger(paths.ledger);
+    const provider = new MiadiOAuthProvider(oauthState, deps.identify);
+    const miadi = new MiadiClient(config.miadiUrl, deps.fetchImpl);
+    const reviews = new ReviewClient(config.reviewUrl, config.reviewToken, deps.fetchImpl);
+    const publicUrl = new URL(config.publicUrl);
+    const mcpUrl = new URL("/mcp", publicUrl);
+    const app = express();
+    app.disable("x-powered-by");
+    // cloudflared reaches the connector over loopback; only that hop is trusted for the client address.
+    app.set("trust proxy", "loopback");
+    app.get("/health", (_req, res) => {
+        res.json({ ok: true, service: "@miadi/connector", version: VERSION });
+    });
+    app.use(mcpAuthRouter({
+        provider,
+        issuerUrl: publicUrl,
+        baseUrl: publicUrl,
+        resourceServerUrl: mcpUrl,
+        scopesSupported: SCOPES,
+        resourceName: "Miadi",
+        serviceDocumentationUrl: new URL("https://github.com/jgwill/Miadi/tree/main/packages/connector"),
+    }));
+    app.post("/authorize/confirm", express.urlencoded({ extended: false, limit: "16kb" }), (req, res, next) => {
+        provider.confirm(req, res).catch(next);
+    });
+    registerApprovalRoutes(app, {
+        config,
+        ledger,
+        miadi,
+        identify: deps.identify,
+        fetchImpl: deps.fetchImpl,
+        factoryDir: deps.factoryDir,
+        tmuxSessions: deps.tmuxSessions,
+    });
+    const auth = requireBearerAuth({
+        verifier: provider,
+        requiredScopes: ["miadi:read"],
+        resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(mcpUrl),
+    });
+    const handle = async (req, res) => {
+        const ctx = { config, miadi, reviews, ledger, oauthState, factoryDir: deps.factoryDir };
+        const server = new McpServer({ name: "miadi", version: VERSION }, { instructions: INSTRUCTIONS });
+        registerTools(server, ctx);
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+        res.on("close", () => {
+            transport.close().catch(() => { });
+            server.close().catch(() => { });
+        });
+        try {
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+        }
+        catch (error) {
+            if (!res.headersSent) {
+                res.status(500).json({ jsonrpc: "2.0", error: { code: -32603, message: "Internal error" }, id: null });
+            }
+            console.error("[connector] /mcp", error);
+        }
+    };
+    app.post("/mcp", auth, express.json({ limit: "4mb" }), handle);
+    app.get("/mcp", auth, (_req, res) => {
+        res.status(405).set("Allow", "POST").json({ jsonrpc: "2.0", error: { code: -32000, message: "Method not allowed" }, id: null });
+    });
+    app.delete("/mcp", auth, (_req, res) => {
+        res.status(405).set("Allow", "POST").json({ jsonrpc: "2.0", error: { code: -32000, message: "Method not allowed" }, id: null });
+    });
+    return { app, provider, ledger };
+}
+export const INSTRUCTIONS = `Miadi is a relational software factory: agent sessions, Miadi reviews of screenwalks, Chronicle episodes, talking circles and the five accountable circles (Story, Stewardship, Engineering, Evaluation, Continuity) across three domains (Creative, Ceremonial, Engineering).
+
+Start with get_capabilities: it says who you are signed in as, which tools are live, and which return not_implemented.
+
+Rules every tool keeps:
+- Every record names the person who made it, with a claim category: observed, hypothesis, desired_future, fiction or verified_implementation. Keep fiction and desired futures apart from what was observed.
+- Requests (runs, review operations, Deep Diver, review-to-episode links, session completion, calendar events) are recorded as awaiting_approval. Nothing runs, publishes or closes until a person approves it in Miadi.
+- An unknown id is answered as not found, never invented. A missing backing service is answered as unavailable.
+- Use the miadi-review:<uuid>, miadi-chronicle://<n>, owner/repo#n and session:<uuid> reference forms.`;

package/dist/store.d.ts

@@ -0,0 +1,23 @@
+export declare function digest(secret: string): string;
+export declare function newSecret(bytes?: number): string;
+export declare function ensureStateDir(dir: string): void;
+export declare class JsonFile<T> {
+    private readonly path;
+    private readonly empty;
+    constructor(path: string, empty: () => T);
+    read(): T;
+    write(value: T): void;
+    update(fn: (value: T) => void): T;
+}
+export declare class Ledger<R extends {
+    id: string;
+}> {
+    private readonly path;
+    constructor(path: string);
+    append(record: R): R;
+    all(): R[];
+}
+export declare function statePaths(dir: string): {
+    oauth: string;
+    ledger: string;
+};

package/dist/store.js

@@ -0,0 +1,89 @@
+/**
+ * The connector's own state, kept in one directory (default
+ * /srv/miadi/connector, which the daily /srv/miadi backup carries).
+ *
+ * - oauth.json   registered OAuth clients, pending sign-ins, codes and tokens.
+ *                Tokens are stored as sha256 digests, never as issued. The
+ *                person's Miadi token is kept so the connector can act as
+ *                them; the directory is created 0700 for that reason.
+ * - ledger.jsonl the records people contribute through the connector
+ *                (observations, handoffs, proposals). Append-only: a record
+ *                is never edited, a later record supersedes it.
+ */
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { createHash, randomBytes } from "node:crypto";
+import { join } from "node:path";
+import { readJsonSafe, writeJsonAtomic } from "@miadi/node-service-kit/json";
+export function digest(secret) {
+    return createHash("sha256").update(secret).digest("hex");
+}
+export function newSecret(bytes = 32) {
+    return randomBytes(bytes).toString("base64url");
+}
+export function ensureStateDir(dir) {
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try {
+        chmodSync(dir, 0o700);
+    }
+    catch {
+        /* a directory owned by another user keeps its mode; reads still work */
+    }
+}
+export class JsonFile {
+    path;
+    empty;
+    constructor(path, empty) {
+        this.path = path;
+        this.empty = empty;
+    }
+    read() {
+        const r = readJsonSafe(this.path);
+        if (r.ok)
+            return r.data;
+        if (r.missing)
+            return this.empty();
+        throw new Error(`${this.path} could not be read (${r.corrupt ? "corrupt" : r.code})`);
+    }
+    write(value) {
+        writeJsonAtomic(this.path, value);
+    }
+    update(fn) {
+        const value = this.read();
+        fn(value);
+        this.write(value);
+        return value;
+    }
+}
+export class Ledger {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    append(record) {
+        appendFileSync(this.path, JSON.stringify(record) + "\n", { mode: 0o600 });
+        return record;
+    }
+    all() {
+        if (!existsSync(this.path))
+            return [];
+        const out = [];
+        for (const line of readFileSync(this.path, "utf8").split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch {
+                /* a torn last line from a crash is skipped, not fatal */
+            }
+        }
+        return out;
+    }
+}
+export function statePaths(dir) {
+    return {
+        oauth: join(dir, "oauth.json"),
+        ledger: join(dir, "ledger.jsonl"),
+    };
+}

package/dist/tools.d.ts

@@ -0,0 +1,19 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ConnectorConfig } from "./config.js";
+import type { MiadiClient } from "./miadi.js";
+import type { ReviewClient } from "./reviews.js";
+import type { JsonFile, Ledger } from "./store.js";
+import type { OAuthState } from "./oauth.js";
+import { type ConnectorRecord } from "./records.js";
+export interface ToolContext {
+    config: ConnectorConfig;
+    miadi: MiadiClient;
+    reviews: ReviewClient;
+    ledger: Ledger<ConnectorRecord>;
+    oauthState: JsonFile<OAuthState>;
+    /** The factory directory holding queue/ (default ~/.miadi/factory). */
+    factoryDir?: string;
+}
+export declare function registerTools(server: McpServer, ctx: ToolContext): void;
+/** What get_capabilities reports for each tool. */
+export declare const TOOL_STATUS: Record<string, string>;