@capitalthought/fairsies-mcp 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,17 @@
+interface ClientConfig {
+    baseUrl: string;
+    bearer: string;
+}
+export declare class FairsiesClient {
+    private cfg;
+    constructor(cfg: ClientConfig);
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, body: unknown): Promise<T>;
+}
+export declare class ClientError extends Error {
+    status: number;
+    bodySnippet: string;
+    constructor(status: number, bodySnippet: string);
+}
+export declare function fromEnv(): FairsiesClient;
+export {};

package/dist/client.js

@@ -0,0 +1,52 @@
+// Thin HTTP client for the fairsies Worker admin API.
+// Auth: ADMIN_BEARER_TOKEN (env var, sourced from 1P at server boot).
+export class FairsiesClient {
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    async get(path) {
+        const r = await fetch(`${this.cfg.baseUrl}${path}`, {
+            headers: { authorization: `Bearer ${this.cfg.bearer}` },
+        });
+        if (!r.ok) {
+            const text = await r.text();
+            throw new ClientError(r.status, text.slice(0, 200));
+        }
+        return (await r.json());
+    }
+    async post(path, body) {
+        const r = await fetch(`${this.cfg.baseUrl}${path}`, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${this.cfg.bearer}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!r.ok) {
+            const text = await r.text();
+            throw new ClientError(r.status, text.slice(0, 200));
+        }
+        return (await r.json());
+    }
+}
+export class ClientError extends Error {
+    status;
+    bodySnippet;
+    constructor(status, bodySnippet) {
+        super(`fairsies admin HTTP ${status}: ${bodySnippet}`);
+        this.status = status;
+        this.bodySnippet = bodySnippet;
+        this.name = "FairsiesClientError";
+    }
+}
+export function fromEnv() {
+    const baseUrl = process.env.FAIRSIES_BASE_URL ?? "https://my.fairsies.com";
+    const bearer = process.env.FAIRSIES_ADMIN_BEARER;
+    if (!bearer) {
+        throw new Error("FAIRSIES_ADMIN_BEARER not set. Load via:\n" +
+            "  export FAIRSIES_ADMIN_BEARER=$(~/.claude/bin/op-logged read 'op://Fairsies/clrghn7lxfwh6fyfy5kkmj3t34/credential')");
+    }
+    return new FairsiesClient({ baseUrl, bearer });
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * fairsies MCP server.
+ *
+ * Agent interface to the 7502 Friends week-selection cycle.
+ * Transport: stdio. Backs the 10 Phase 3 tools defined in
+ * docs/plans/2026-05-16-impl-plan/implementation-plan.md.
+ *
+ * All tools call the Worker admin API at $FAIRSIES_BASE_URL (default
+ * https://my.fairsies.com) authed via $FAIRSIES_ADMIN_BEARER. The Worker
+ * owns D1 access; the MCP server is a thin client.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+/**
+ * fairsies MCP server.
+ *
+ * Agent interface to the 7502 Friends week-selection cycle.
+ * Transport: stdio. Backs the 10 Phase 3 tools defined in
+ * docs/plans/2026-05-16-impl-plan/implementation-plan.md.
+ *
+ * All tools call the Worker admin API at $FAIRSIES_BASE_URL (default
+ * https://my.fairsies.com) authed via $FAIRSIES_ADMIN_BEARER. The Worker
+ * owns D1 access; the MCP server is a thin client.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { fromEnv, ClientError } from "./client.js";
+const server = new McpServer({ name: "fairsies-mcp", version: "0.1.0" }, {
+    capabilities: { tools: {} },
+    instructions: "fairsies — agent interface to the 7502 Friends week-selection cycle. " +
+        "All partner-facing comms go through the Worker (iMessage primary + email backup). " +
+        "Call `overview` first when investigating; never invent partner_ids or week dates — " +
+        "always pull them from `get_cycle_status` or `get_allocation`.",
+});
+function ok(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+}
+function err(code, message, extra) {
+    return ok({ ok: false, code, message, ...(extra ?? {}) });
+}
+function wrapErr(e) {
+    if (e instanceof ClientError) {
+        return err("admin_http", e.message, { status: e.status });
+    }
+    return err("exception", e instanceof Error ? e.message : String(e));
+}
+// ---------- Tool 1: overview (Inspectable State, Agent First §9) ----------
+server.registerTool("overview", {
+    description: "Operational snapshot: cycle counts, recent activity tail, channel-success rates, watchdog health. Call this first to orient.",
+    inputSchema: {},
+}, async () => {
+    try {
+        const data = await fromEnv().get("/admin/overview");
+        return ok(data);
+    }
+    catch (e) {
+        return wrapErr(e);
+    }
+});
+// ---------- Tool 2: get_cycle_status ----------
+server.registerTool("get_cycle_status", {
+    description: "Current state of a cycle: status, milestone progress, partner submissions outstanding, recent comms.",
+    inputSchema: {
+        cycle_id: z
+            .string()
+            .optional()
+            .describe("Cycle ID (e.g. '2026-2H'). Omit for current active cycle."),
+    },
+}, async ({ cycle_id }) => {
+    try {
+        const path = cycle_id
+            ? `/admin/cycle-status?cycle_id=${encodeURIComponent(cycle_id)}`
+            : "/admin/cycle-status";
+        const data = await fromEnv().get(path);
+        return ok(data);
+    }
+    catch (e) {
+        return wrapErr(e);
+    }
+});
+// ---------- Tool 3: list_pending_swaps ----------
+server.registerTool("list_pending_swaps", {
+    description: "Swap proposals awaiting partner confirmation.",
+    inputSchema: {
+        cycle_id: z.string().optional().describe("Cycle ID; omit for current cycle."),
+    },
+}, async ({ cycle_id }) => {
+    try {
+        const path = cycle_id
+            ? `/admin/swaps?status=proposed&cycle_id=${encodeURIComponent(cycle_id)}`
+            : "/admin/swaps?status=proposed";
+        return ok(await fromEnv().get(path));
+    }
+    catch (e) {
+        return wrapErr(e);
+    }
+});
+// ---------- Tool 4: propose_swap ----------
+server.registerTool("propose_swap", {
+    description: "Initiate a swap proposal between two partners. Requires confirmation from the counterparty before locking.",
+    inputSchema: {
+        cycle_id: z.string().describe("Cycle ID (e.g. '2026-2H')."),
+        from_partner: z.string().describe("Partner proposing the swap (currently owns week_a)."),
+        to_partner: z.string().describe("Counterparty (currently owns week_b)."),
+        week_a: z.string().describe("ISO date (YYYY-MM-DD), week the proposer is giving up."),
+        week_b: z.string().describe("ISO date (YYYY-MM-DD), week the proposer wants."),
+        ttl_seconds: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Optional TTL override (default 7 days)."),
+    },
+}, async ({ cycle_id, from_partner, to_partner, week_a, week_b, ttl_seconds }) => {
+    try {
+        return ok(await fromEnv().post("/admin/swaps/propose", {
+            cycle_id,
+            from_partner_id: from_partner,
+            to_partner_id: to_partner,
+            week_from: week_a,
+            week_to: week_b,
+            ttl_seconds,
+        }));
+    }
+    catch (e) {
+        return wrapErr(e);
+    }
+});
+// ---------- Tool 5: confirm_swap ----------
+server.registerTool("confirm_swap", {
+    description: "Counterparty confirms a pending swap. Atomically flips picks ownership and locks the trade.",
+    inputSchema: {
+        swap_id: z.string().describe("Swap proposal ID returned by propose_swap."),
+        partner_id: z.string().describe("Confirming partner (must be the counterparty)."),
+    },
+}, async ({ swap_id, partner_id }) => {
+    try {
+        return ok(await fromEnv().post(`/admin/swaps/${encodeURIComponent(swap_id)}/confirm`, {
+            confirming_partner_id: partner_id,
+        }));
+    }
+    catch (e) {
+        return wrapErr(e);
+    }
+});
+// ---------- Tool 6: release_to_rental_pool ----------
+server.registerTool("release_to_rental_pool", {
+    description: "Partner releases an assigned week. intent='rental' triggers Schedule II §5 ROFR (offers the week to other partners at 50% net credit for 7 days). intent='gift' or 'donate' is logged but contract-exempt from ROFR per §5(d).",
+    inputSchema: {
+        cycle_id: z.string().describe("Cycle ID (e.g. '2026-2H')."),
+        week_friday: z.string().describe("ISO date of the week (Friday check-in)."),
+        offering_partner_id: z.string().describe("Releasing partner (current pick owner)."),
+        intent: z.enum(["rental", "gift", "donate"]).describe("rental=ROFR fires; gift/donate=just logged."),
+        gross_rate_usd: z
+            .number()
+            .positive()
+            .optional()
+            .describe("Required for intent=rental: gross Rosewood Signature Penthouse rate for the full week (USD total). Net credit to claiming partner = gross × 50%. Rosewood's booking engine blocks scraping; rate must come from the partner or Sebastien Dental/Michael Chiche at Rosewood."),
+    },
+}, async ({ cycle_id, week_friday, offering_partner_id, intent, gross_rate_usd }) => {
+    try {
+        return ok(await fromEnv().post("/admin/rental-release", {
+            cycle_id,
+            week_friday,
+            offering_partner_id,
+            intent,
+            gross_rate_usd,
+        }));
+    }
+    catch (e) {
+        return wrapErr(e);
+    }
+});
+// ---------- Tool 7: get_allocation ----------
+server.registerTool("get_allocation", {
+    description: "Per-partner allocation for a cycle: assigned weeks + priority-vs-fallback reason per pick.",
+    inputSchema: {
+        cycle_id: z.string().optional(),
+    },
+}, async ({ cycle_id }) => {
+    try {
+        const path = cycle_id
+            ? `/admin/allocation?cycle_id=${encodeURIComponent(cycle_id)}`
+            : "/admin/allocation";
+        const data = await fromEnv().get(path);
+        return ok(data);
+    }
+    catch (e) {
+        return wrapErr(e);
+    }
+});
+// ---------- Tool 8: list_recent_inbound ----------
+server.registerTool("list_recent_inbound", {
+    description: "Recent inbound iMessages with parsed intents. Use to triage 'what did Jeffrey just say'.",
+    inputSchema: {
+        partner_id: z.string().optional(),
+        limit: z.number().int().positive().max(50).default(10),
+    },
+}, async ({ partner_id, limit }) => {
+    try {
+        const params = new URLSearchParams();
+        if (partner_id)
+            params.set("partner_id", partner_id);
+        params.set("limit", String(limit));
+        const data = await fromEnv().get(`/admin/inbound?${params.toString()}`);
+        return ok(data);
+    }
+    catch (e) {
+        return wrapErr(e);
+    }
+});
+// ---------- Tool 9: send_partner_imessage ----------
+server.registerTool("send_partner_imessage", {
+    description: "Operator-side: send a partner a one-off iMessage via the mikeybot bridge. Logged to comms_log like any milestone send. Use sparingly — partners expect cycle-driven messages.",
+    inputSchema: {
+        partner_id: z.string(),
+        body: z.string().max(1500),
+        milestone: z
+            .string()
+            .optional()
+            .describe("Optional label for comms_log (e.g. 'operator-nudge', 'swap-broker')."),
+    },
+}, async ({ partner_id, body, milestone }) => {
+    try {
+        const data = await fromEnv().post("/admin/send-imessage", {
+            partner_id,
+            body,
+            milestone: milestone ?? "operator-oneoff",
+        });
+        return ok(data);
+    }
+    catch (e) {
+        return wrapErr(e);
+    }
+});
+// ---------- Tool 10: resend_milestone ----------
+server.registerTool("resend_milestone", {
+    description: "Replay a specific milestone send to one channel for one partner. Use when iMessage fails but email succeeded and operator wants to retry iMessage.",
+    inputSchema: {
+        cycle_id: z.string(),
+        partner_id: z.string(),
+        milestone: z.string(),
+        channel: z.enum(["imessage", "email"]),
+    },
+}, async ({ cycle_id, partner_id, milestone, channel }) => {
+    try {
+        const data = await fromEnv().post("/admin/resend", {
+            cycle_id,
+            partner_id,
+            milestone,
+            channel,
+        });
+        return ok(data);
+    }
+    catch (e) {
+        return wrapErr(e);
+    }
+});
+// ---------- start stdio transport ----------
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("fairsies-mcp boot error:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@capitalthought/fairsies-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for fairsies — agent interface to the 7502 Friends week-selection cycle. Tools to read cycle state, propose swaps, release weeks to rental pool, and inspect operational state.",
+  "license": "MIT",
+  "author": "Capital Thought",
+  "type": "module",
+  "bin": {
+    "fairsies-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}