@hiabhee/archdraw-mcp-server 1.0.4 → 1.0.6

package/README.md

@@ -0,0 +1,119 @@
+# @hiabhee/archdraw-mcp-server
+
+The MCP server for [ArchDraw](https://archdraw.hiabhee.online). It lets an AI agent make, change, validate, and export software architecture diagrams.
+
+The server uses the same Mermaid → Dagre layout pipeline as the ArchDraw editor. Each new diagram gets a preview link that you can open in a browser.
+
+This document uses ASD-STE100 Simplified Technical English.
+
+## Select a connection type
+
+| Connection type | Value | Use it when |
+| --- | --- | --- |
+| **Remote (HTTP)** | `https://archdraw.hiabhee.online/api/mcp` | The client can connect to a remote MCP server. This is the recommended type. You do not install this package. |
+| **Local (stdio)** | `npx -y @hiabhee/archdraw-mcp-server@1.0.6` | The client can only start a local process. |
+
+For the steps for each client (Claude Code, Claude apps, Codex, Cursor, VS Code, Gemini CLI, OpenCode, and others), refer to the [connection guide](https://archdraw.hiabhee.online/docs/connect-agents).
+
+## Use the local server
+
+### Requirements
+
+- Node.js 18 or later
+- Network access to `archdraw.hiabhee.online`
+
+### Configuration
+
+Most clients use this format:
+
+```json
+{
+  "mcpServers": {
+    "archdraw": {
+      "command": "npx",
+      "args": ["-y", "@hiabhee/archdraw-mcp-server@1.0.6"],
+      "env": {
+        "API_BASE_URL": "https://archdraw.hiabhee.online"
+      }
+    }
+  }
+}
+```
+
+> **CAUTION:** You must set `API_BASE_URL`. If you do not set it, the server starts and shows its tools, but `generate_diagram`, `fix_layout`, and preview links do not operate.
+
+### Environment variables
+
+| Variable | Necessary | Function |
+| --- | --- | --- |
+| `API_BASE_URL` | Yes | The ArchDraw web API that does the layout, publishes previews, and keeps sessions. Use `https://archdraw.hiabhee.online`, or the URL of your own deployment. |
+
+## Link a repository to a live project
+
+A live project is an ArchDraw canvas that shows which coding-agent session works on which component. To connect a repository to a live project:
+
+1. In the ArchDraw editor, open the canvas and select **Make live project**.
+2. In the repository, run:
+
+   ```bash
+   npx -y @hiabhee/archdraw-mcp-server@1.0.6 link --api https://archdraw.hiabhee.online
+   ```
+
+3. In the editor, select **Live project → Connect an agent** and enter the code that the command shows.
+
+The command keeps the link in `~/.archdraw/projects.json` (mode `0600`), outside the repository. The file contains a project token. Do not share it. Other commands:
+
+| Command | Result |
+| --- | --- |
+| `link --api <URL>` | Links the current repository (or its main repository, for a git worktree). |
+| `status` | Shows the project that the current repository is linked to. |
+| `unlink` | Removes the local link. To revoke the token, select **Stop** in the editor. |
+
+The ArchDraw plugin for Claude Code uses this link to report the files that each session edits. It sends file paths only.
+
+## Tools
+
+| Tool | Function |
+| --- | --- |
+| `read_me` | Gives the reference guide for the agent. The agent calls it first. |
+| `generate_diagram` | Makes a diagram from Mermaid text or from nodes and edges. |
+| `update_diagram` | Adds, removes, or changes nodes and edges in the current diagram. |
+| `get_diagram_state` | Gives the nodes and edges of the current diagram. |
+| `validate_diagram` | Finds structural problems and gives recommendations. |
+| `fix_layout` | Calculates the layout again with the ArchDraw editor pipeline. |
+| `apply_template` | Loads an architecture template. |
+| `list_templates` | Gives the list of templates. |
+| `list_node_types` | Gives the list of component types in the ArchDraw library. |
+| `save_checkpoint` | Saves the current diagram with a name. |
+| `load_checkpoint` | Restores a saved diagram. |
+| `export_diagram` | Exports the diagram as JSON, PNG, or SVG. |
+
+## Data and privacy
+
+- The server sends the diagram content that the agent gives it to `API_BASE_URL`. This includes component names, labels, connections, and Mermaid text. The server does not read your source files.
+- Each new diagram gets a preview link by default. Anyone with the link can see the diagram. The link expires after 7 days. To prevent a link, tell the agent to keep the diagram private (`publish: false`).
+- The local server keeps the working diagram and its checkpoints in memory. It discards them when the process stops.
+
+> **WARNING:** Do not put passwords, API keys, or other secrets in diagram labels.
+
+Refer to the [privacy policy](https://archdraw.hiabhee.online/privacy).
+
+## Use the server in your own code
+
+The package exports a server factory for Streamable HTTP hosts:
+
+```ts
+import { createArchDrawMCPServer, handleMcpHttpRequest } from '@hiabhee/archdraw-mcp-server/server';
+```
+
+The hosted endpoint at `/api/mcp` uses this export.
+
+## Links
+
+- [Source code](https://github.com/hiabhee/ArchDraw/tree/main/mcp-server)
+- [Connection guide](https://archdraw.hiabhee.online/docs/connect-agents)
+- [Issues](https://github.com/hiabhee/ArchDraw/issues)
+
+## License
+
+MIT

package/dist/cli/project-link.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `archdraw-mcp-server link|unlink|status` — pair this git checkout with an
+ * ArchDraw live project. Pairing uses the browser approval flow
+ * (`/api/agentic/pairing`): the CLI shows a code, the user enters it in the
+ * editor's Live project panel, and the CLI receives a project-scoped token.
+ * Output goes to stderr except the final machine-readable line.
+ */
+export declare const PROJECT_COMMANDS: Set<string>;
+interface CliIO {
+    log: (message: string) => void;
+    fetch: typeof fetch;
+    sleep: (ms: number) => Promise<void>;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}
+export declare function runProjectCommand(command: string, argv: string[], io?: CliIO): Promise<number>;
+export {};
+//# sourceMappingURL=project-link.d.ts.map

package/dist/cli/project-link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-link.d.ts","sourceRoot":"","sources":["../../src/cli/project-link.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,eAAO,MAAM,gBAAgB,aAAwC,CAAC;AAItE,UAAU,KAAK;IACb,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB;AA0HD,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAKjH"}

package/dist/cli/project-link.js

@@ -0,0 +1,129 @@
+import { getBinding, removeBinding, resolveRepoRoot, saveBinding, bindingFilePath } from '../lib/project-binding.js';
+/**
+ * `archdraw-mcp-server link|unlink|status` — pair this git checkout with an
+ * ArchDraw live project. Pairing uses the browser approval flow
+ * (`/api/agentic/pairing`): the CLI shows a code, the user enters it in the
+ * editor's Live project panel, and the CLI receives a project-scoped token.
+ * Output goes to stderr except the final machine-readable line.
+ */
+export const PROJECT_COMMANDS = new Set(['link', 'unlink', 'status']);
+const POLL_INTERVAL_MS = 3000;
+const defaultIO = () => ({
+    log: (message) => process.stderr.write(`${message}\n`),
+    fetch,
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+    cwd: process.cwd(),
+    env: process.env,
+});
+function parseArgs(argv) {
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith('--')) {
+            const [key, inline] = arg.slice(2).split('=', 2);
+            flags[key] = inline ?? argv[++i] ?? '';
+        }
+    }
+    return flags;
+}
+function formatUserCode(code) {
+    return code.match(/.{1,4}/g)?.join('-') ?? code;
+}
+function normalizeApiBase(value) {
+    if (!value)
+        return null;
+    try {
+        const url = new URL(value);
+        if (url.protocol !== 'https:' && !['localhost', '127.0.0.1'].includes(url.hostname))
+            return null;
+        return url.origin;
+    }
+    catch {
+        return null;
+    }
+}
+async function link(flags, io) {
+    const apiBase = normalizeApiBase(flags.api || io.env.API_BASE_URL);
+    if (!apiBase) {
+        io.log('Pass the ArchDraw URL: link --api https://archdraw.hiabhee.online (https, or http://localhost for development).');
+        return 2;
+    }
+    const repoRoot = resolveRepoRoot(io.cwd);
+    const start = await io.fetch(`${apiBase}/api/agentic/pairing`, { method: 'POST' });
+    if (!start.ok) {
+        io.log(`Could not start pairing (${start.status}).`);
+        return 1;
+    }
+    const pairing = (await start.json());
+    io.log('');
+    io.log(`Linking ${repoRoot} to an ArchDraw live project.`);
+    io.log(`Open your project canvas in ArchDraw → Live project → Connect an agent, and enter:`);
+    io.log('');
+    io.log(`    ${formatUserCode(pairing.userCode)}`);
+    io.log('');
+    io.log(`Waiting for approval (expires ${new Date(pairing.expiresAt).toLocaleTimeString()})…`);
+    const deadline = new Date(pairing.expiresAt).getTime();
+    while (Date.now() < deadline) {
+        await io.sleep(POLL_INTERVAL_MS);
+        const res = await io.fetch(`${apiBase}/api/agentic/pairing/poll`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ pairingId: pairing.pairingId, pollToken: pairing.pollToken }),
+        });
+        if (res.status === 202)
+            continue;
+        if (res.status === 410)
+            break;
+        const body = (await res.json().catch(() => ({})));
+        if (res.ok && body.status === 'complete' && body.projectId && body.workspaceId) {
+            if (!body.canvasId) {
+                io.log('Approved, but that project is not linked to a canvas. Use "Make live project" on a canvas and try again.');
+                return 1;
+            }
+            saveBinding(repoRoot, {
+                apiBase,
+                canvasId: body.canvasId,
+                agenticProjectId: body.projectId,
+                workspaceId: body.workspaceId,
+                token: pairing.pollToken,
+                linkedAt: new Date().toISOString(),
+            });
+            io.log(`Linked. Credentials saved to ${bindingFilePath()} (outside the repository).`);
+            io.log(`Project canvas: ${apiBase}/editor?canvas=${encodeURIComponent(body.canvasId)}`);
+            return 0;
+        }
+        if (!res.ok && res.status !== 409) {
+            io.log(`Pairing failed (${res.status}).`);
+            return 1;
+        }
+    }
+    io.log('Pairing code expired. Run link again.');
+    return 1;
+}
+function unlink(io) {
+    const repoRoot = resolveRepoRoot(io.cwd);
+    const removed = removeBinding(repoRoot);
+    io.log(removed
+        ? `Unlinked ${repoRoot}. To revoke the credential too, use "Stop" in the editor's Live project panel.`
+        : `${repoRoot} is not linked.`);
+    return 0;
+}
+function status(io) {
+    const repoRoot = resolveRepoRoot(io.cwd);
+    const binding = getBinding(repoRoot);
+    if (!binding) {
+        io.log(`${repoRoot} is not linked to an ArchDraw project.`);
+        return 1;
+    }
+    io.log(`${repoRoot} → ${binding.apiBase}/editor?canvas=${encodeURIComponent(binding.canvasId)} (linked ${binding.linkedAt})`);
+    return 0;
+}
+export async function runProjectCommand(command, argv, io = defaultIO()) {
+    const flags = parseArgs(argv);
+    if (command === 'link')
+        return link(flags, io);
+    if (command === 'unlink')
+        return unlink(io);
+    return status(io);
+}
+//# sourceMappingURL=project-link.js.map

package/dist/cli/project-link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-link.js","sourceRoot":"","sources":["../../src/cli/project-link.ts"],"names":[],"mappings":"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"}