thalixtower-mcp 0.6.0

package/README.md

@@ -0,0 +1,43 @@
+# thalixtower-mcp
+
+Thalix Tower MCP server — exposes `atc_*` tools to MCP-capable agents (Claude Code),
+so an agent coordinates natively instead of running shell commands.
+
+## Configure
+
+Get a **frequency token** from the dashboard (https://tower.thalixinc.ai), then add
+to your project's `.mcp.json` (or Claude settings) — or run `atc init` from
+`thalixtower-cli` to scaffold it:
+
+```jsonc
+{
+  "mcpServers": {
+    "agent-tower": {
+      "command": "npx",
+      "args": ["-y", "thalixtower-mcp"],
+      "env": { "ATC_TOKEN": "atcf_…" }
+    }
+  }
+}
+```
+
+`ATC_API` is optional (defaults to the hosted prod API; set it to target the dev
+stack).
+
+## Tools
+
+`atc_checkin` · `atc_brief` · `atc_standing` · `atc_standing_propose` ·
+`atc_squawk` · `atc_claim` · `atc_clear` · `atc_note` · `atc_notes` ·
+`atc_checkout`.
+
+The checkin brief opens with the agent's **standing orders** — per-project
+instructions assigned via the token's alignment (humans manage these in the
+dashboard or with `atc login`). `atc_standing_propose` lets the agent suggest a
+draft order; a human reviews, activates, and assigns it.
+
+The server shares one session per workspace with the CLI via `.atc/session.json`
+(gitignore `.atc/`), so the CLI, hooks, and MCP never invalidate each other.
+
+Pair it with the coordination block in your `CLAUDE.md`/`AGENTS.md` (see the
+project's `templates/agent-tower.md`) so the agent knows to use these at the
+right moments.

package/dist/index.js

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+var API = (process.env.ATC_API || "https://api.tower.thalixinc.ai").replace(/\/$/, "");
+var TOKEN = process.env.ATC_TOKEN ?? "";
+var ATC_DIR = path.join(process.cwd(), ".atc");
+var SESSION_FILE = path.join(ATC_DIR, "session.json");
+var session = null;
+function readSessionFile() {
+  try {
+    const s = JSON.parse(fs.readFileSync(SESSION_FILE, "utf8"));
+    if (typeof s?.sessionToken === "string" && s.sessionToken) return s;
+  } catch {
+  }
+  return null;
+}
+function writeSessionFile(s) {
+  fs.mkdirSync(ATC_DIR, { recursive: true });
+  fs.writeFileSync(SESSION_FILE, JSON.stringify({ ...s, api: API }, null, 2));
+}
+function clearSessionFile() {
+  try {
+    fs.rmSync(SESSION_FILE);
+  } catch {
+  }
+}
+function workspaceId() {
+  const file = path.join(ATC_DIR, "workspace.json");
+  try {
+    const existing = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (existing.workspaceId) return existing.workspaceId;
+  } catch {
+  }
+  const id = `ws_${randomUUID()}`;
+  fs.mkdirSync(ATC_DIR, { recursive: true });
+  fs.writeFileSync(file, JSON.stringify({ workspaceId: id }, null, 2));
+  return id;
+}
+async function call(bearer, method, apiPath, body) {
+  const res = await fetch(`${API}${apiPath}`, {
+    method,
+    headers: { authorization: `Bearer ${bearer}`, "content-type": "application/json" },
+    body: body ? JSON.stringify(body) : void 0
+  });
+  const text2 = await res.text();
+  let data = {};
+  try {
+    data = text2 ? JSON.parse(text2) : {};
+  } catch {
+    data = { error: text2 };
+  }
+  return { ok: res.ok, status: res.status, data };
+}
+var text = (data, isError = false) => ({
+  content: [{ type: "text", text: typeof data === "string" ? data : JSON.stringify(data, null, 2) }],
+  isError
+});
+var needConfig = () => !API || !TOKEN ? text("ATC_API and ATC_TOKEN must be set in the MCP server env", true) : null;
+async function sessionCall(method, apiPath, body) {
+  if (!session) {
+    const shared = readSessionFile();
+    if (shared) session = shared;
+  }
+  if (!session) return null;
+  let r = await call(session.sessionToken, method, apiPath, body);
+  if (r.status === 401) {
+    const shared = readSessionFile();
+    if (shared && shared.sessionToken !== session.sessionToken) {
+      r = await call(shared.sessionToken, method, apiPath, body);
+      if (r.ok) session = shared;
+    }
+  }
+  return r;
+}
+var sessionResult = (r) => r ? text(r.data, !r.ok) : text("not checked in \u2014 call atc_checkin first", true);
+var server = new McpServer({ name: "thalix-tower", version: "0.6.0" });
+server.registerTool(
+  "atc_checkin",
+  {
+    description: "Contact the Tower: declare identity + task, get your callsign and a brief. If the brief carries standing orders, read and follow them.",
+    inputSchema: { task: z.string().optional(), callsign: z.string().optional(), cli: z.string().optional() }
+  },
+  async (args) => {
+    const cfg = needConfig();
+    if (cfg) return cfg;
+    const r = await call(TOKEN, "POST", "/v1/sessions", {
+      workspaceId: workspaceId(),
+      callsign: args.callsign,
+      cli: args.cli ?? "claude",
+      worktree: process.cwd(),
+      task: args.task
+    });
+    if (!r.ok) return text(r.data, true);
+    session = { callsign: r.data.callsign, sessionToken: r.data.sessionToken };
+    writeSessionFile(session);
+    return text({ callsign: r.data.callsign, brief: r.data.brief });
+  }
+);
+server.registerTool(
+  "atc_brief",
+  { description: "Orient: standing orders + roster + claims + conflicts touching you + NOTAMs + traffic (unacked inbox count + preview).", inputSchema: {} },
+  async () => sessionResult(await sessionCall("GET", "/v1/brief"))
+);
+server.registerTool(
+  "atc_standing",
+  {
+    description: "The frequency's standing orders in full (project-wide instructions every session must follow; briefs truncate long ones).",
+    inputSchema: {}
+  },
+  async () => sessionResult(await sessionCall("GET", "/v1/standing"))
+);
+server.registerTool(
+  "atc_squawk",
+  {
+    description: "Broadcast status (also the heartbeat). Returns conflicts touching your claims + unacked traffic count.",
+    inputSchema: { status: z.string().optional(), code: z.enum(["working", "blocked", "review", "mayday"]).optional() }
+  },
+  async (args) => sessionResult(await sessionCall("POST", "/v1/squawk", args))
+);
+server.registerTool(
+  "atc_claim",
+  {
+    description: "Request clearance on a path glob. Returns conflicts INLINE \u2014 if non-empty, do NOT edit; squawk blocked and tell the human.",
+    inputSchema: { glob: z.string() }
+  },
+  async (args) => sessionResult(await sessionCall("POST", "/v1/claims", { glob: args.glob }))
+);
+server.registerTool(
+  "atc_clear",
+  { description: "Release a claim (or all of yours if glob omitted).", inputSchema: { glob: z.string().optional() } },
+  async (args) => sessionResult(await sessionCall("POST", "/v1/clear", { glob: args.glob }))
+);
+server.registerTool(
+  "atc_note",
+  {
+    description: "Write a NOTAM to the durable decision log. supersedes retires an older NOTAM.",
+    inputSchema: {
+      body: z.string(),
+      tags: z.array(z.string()).optional(),
+      pinned: z.boolean().optional(),
+      supersedes: z.string().optional()
+    }
+  },
+  async (args) => sessionResult(await sessionCall("POST", "/v1/notams", args))
+);
+server.registerTool(
+  "atc_notes",
+  {
+    description: "List the decision log (NOTAMs), optionally filtered by tag \u2014 or pass id for one full NOTAM body (briefs truncate).",
+    inputSchema: { tag: z.string().optional(), id: z.string().optional() }
+  },
+  async (args) => {
+    if (args.id) {
+      return sessionResult(await sessionCall("GET", `/v1/notams/${encodeURIComponent(args.id)}`));
+    }
+    const q = args.tag ? `?tag=${encodeURIComponent(args.tag)}` : "";
+    return sessionResult(await sessionCall("GET", `/v1/notams${q}`));
+  }
+);
+server.registerTool(
+  "atc_checkout",
+  { description: "Leave cleanly: release claims and drop off the board.", inputSchema: {} },
+  async () => {
+    const r = await sessionCall("POST", "/v1/checkout");
+    session = null;
+    clearSessionFile();
+    return sessionResult(r);
+  }
+);
+server.registerTool(
+  "atc_call",
+  {
+    description: "Call another agent on this frequency (or '*' for everyone): writes to their durable inbox; they receive it at their next checkpoint. Mail to offline callsigns queues.",
+    inputSchema: { to: z.string(), body: z.string() }
+  },
+  async (args) => sessionResult(await sessionCall("POST", "/v1/calls", { to: args.to, body: args.body }))
+);
+server.registerTool(
+  "atc_traffic",
+  {
+    description: "Read your inbox (calls from other agents). Acks on read by default \u2014 answer anything that needs answering via atc_call. keepUnread:true to peek without acking.",
+    inputSchema: { keepUnread: z.boolean().optional() }
+  },
+  async (args) => {
+    const r = await sessionCall("GET", "/v1/traffic");
+    if (!r) return text("not checked in \u2014 call atc_checkin first", true);
+    if (!r.ok) return text(r.data, true);
+    if (args.keepUnread !== true) {
+      await sessionCall("POST", "/v1/traffic/ack", { all: true });
+    }
+    return text(r.data);
+  }
+);
+server.registerTool(
+  "atc_standing_propose",
+  {
+    description: "Propose a standing order DRAFT for this frequency (saved to the library; a human reviews, activates, and assigns it). Use for durable instructions future sessions should receive.",
+    inputSchema: { name: z.string(), body: z.string() }
+  },
+  async (args) => sessionResult(await sessionCall("POST", "/v1/standing-orders", { name: args.name, body: args.body }))
+);
+await server.connect(new StdioServerTransport());

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "thalixtower-mcp",
+  "version": "0.6.0",
+  "description": "Thalix Tower MCP server — exposes atc_* tools to MCP-capable agents (Claude Code).",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/manateeit/thalix-tower.git",
+    "directory": "mcp"
+  },
+  "homepage": "https://tower.thalixinc.ai",
+  "keywords": [
+    "agent-tower",
+    "mcp",
+    "model-context-protocol",
+    "coding-agents",
+    "coordination",
+    "claude"
+  ],
+  "type": "module",
+  "bin": {
+    "agent-tower-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --target=node20 --format=esm --outfile=dist/index.js --banner:js='#!/usr/bin/env node' --packages=external",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.16.10",
+    "esbuild": "^0.24.0",
+    "typescript": "^5.6.2"
+  }
+}