@bridge-ds/mcp 0.3.0 → 0.3.1

package/README.md

@@ -7,28 +7,31 @@ propose token changes as reviewable branches and pull requests. It never writes
 Free and open source (MIT). Local, no backend, no account: it reads files on your disk, or a GitHub repo
 with your own token.
 
-> On npm: `npx -y @bridge-ds/mcp` runs it, nothing to build. The local path form (`node packages/mcp/dist/index.js`)
-> is for working on the server itself.
-
 ## Run it
 
+From npm, nothing to build:
+
 ```sh
-npm run mcp:build                                   # builds packages/mcp and packages/cli
-node packages/mcp/dist/index.js --root .            # local repo (default: current directory)
-node packages/mcp/dist/index.js --repo owner/name   # GitHub repo, read-only
-GITHUB_TOKEN=... node packages/mcp/dist/index.js --repo owner/name   # GitHub repo, can open PRs
+npx -y @bridge-ds/mcp --repo owner/name                  # GitHub repo, read-only
+GITHUB_TOKEN=... npx -y @bridge-ds/mcp --repo owner/name # GitHub repo, can open PRs
+npx -y @bridge-ds/mcp --root .                           # local folder (default: current directory)
+npx -y @bridge-ds/mcp --help
 ```
 
 Connect it to Claude Code:
 
 ```sh
-claude mcp add bridge -- npx -y @bridge-ds/mcp --root /abs/path/to/your-ds
-# or a GitHub repo (pull requests need a token):
+claude mcp add bridge -s user -- npx -y @bridge-ds/mcp --repo owner/name
+# so Claude can open pull requests (a fine-grained token limited to that repo):
 claude mcp add bridge -s user -e GITHUB_TOKEN=your-github-token -- npx -y @bridge-ds/mcp --repo owner/name
+# or a local checkout:
+claude mcp add bridge -- npx -y @bridge-ds/mcp --root /abs/path/to/your-ds
 ```
 
-Or commit a project `.mcp.json` (this repo has one), or run `bridge init`. Claude Desktop, other clients
-and the full guide: [docs/AI.md](../../docs/AI.md).
+Or commit a project `.mcp.json`. Claude Desktop, other clients and the full guide: [docs/AI.md](../../docs/AI.md).
+
+Working on the server itself: `npm run mcp:build` in a clone of this repo builds it to
+`packages/mcp/dist/index.js`, which this repo's own `.mcp.json` runs.
 
 ## Modes
 

package/dist/{chunk-GABRGCKY.js → chunk-I3TL76GK.js}

@@ -1039,6 +1039,25 @@ var GitHubClient = class _GitHubClient {
       throw new GitHubError(422, `GitHub refused to mark #${n} ready for review${detail ? `: ${detail}` : "."} Use "Ready for review" on GitHub instead.`, detail);
     }
   }
+  /**
+   * Turns an open pull request back into a draft: the GraphQL mutation convertPullRequestToDraft (REST cannot set
+   * `draft` either), same token. No-op when it is already a draft.
+   */
+  async convertToDraft(n) {
+    this.assertToken("Turning a pull request back into a draft");
+    const pr = await this.request("GET", `${this.repoPath}/pulls/${n}`);
+    if (pr.draft === true) return;
+    if (pr.state && pr.state !== "open") throw new GitHubError(422, `Pull request #${n} is ${pr.state}: only an open one can go back to draft.`);
+    if (!pr.node_id) throw new GitHubError(422, `Pull request #${n} has no node id: convert it to draft on GitHub.`);
+    const r = await this.request("POST", "/graphql", {
+      query: "mutation($id: ID!) { convertPullRequestToDraft(input: { pullRequestId: $id }) { pullRequest { number isDraft } } }",
+      variables: { id: pr.node_id }
+    });
+    if (r?.errors?.length) {
+      const detail = r.errors.map((e) => e.message).filter(Boolean).join(" ");
+      throw new GitHubError(422, `GitHub refused to turn #${n} back into a draft${detail ? `: ${detail}` : "."} Use "Convert to draft" on GitHub instead.`, detail);
+    }
+  }
   async createPullRequest(input) {
     this.assertWritableBranch(input.head, input.base);
     const r = await this.request(
@@ -3000,7 +3019,7 @@ function explorationPrBody(e, ctx) {
     `- **Promote:** in Bridge Studio (Changes, Explorations, Promote to review) or \`bridge explore promote ${slug2}\`. Bridge marks the pull request ready for review, removes the \`${EXPLORATION_LABEL}\` label and the exploration note, and adds the tier labels. Then it goes through the usual review.`,
     "- **Close:** close this pull request. The branch stays for reference; the preview prerelease is removed.",
     "",
-    `<!-- ${MARK} ${JSON.stringify({ name: e.name.trim(), purpose: e.purpose.trim(), slug: slug2, ...e.useCase ? { useCase: e.useCase } : {}, ...experimental.length ? { experimental } : {}, ...e.author ? { author: e.author } : {}, ...e.startedAt ? { startedAt: e.startedAt } : {} }).replace(/-->/g, "--\\u003e")} -->`
+    `<!-- ${MARK} ${JSON.stringify({ name: e.name.trim(), purpose: e.purpose.trim(), slug: slug2, ...e.useCase ? { useCase: e.useCase } : {}, ...experimental.length ? { experimental } : {}, ...e.author ? { author: e.author } : {}, ...e.startedAt ? { startedAt: e.startedAt } : {}, ...e.source ? { source: e.source } : {}, ...e.agent ? { agent: e.agent } : {} }).replace(/-->/g, "--\\u003e")} -->`
   );
   return lines.join("\n");
 }
@@ -3420,6 +3439,8 @@ function explorationSummary(p, _owner, _repo, s) {
     status: explorationStatus({ state: p.state, labels: p.labels, headRef: p.headRef, body: p.body }),
     draft: p.draft,
     author: e?.author ?? p.author,
+    ...e?.source ? { source: e.source } : {},
+    ...e?.agent ? { agent: e.agent } : {},
     updatedAt: p.updatedAt,
     headSha: p.headSha,
     previews: previewLinks(s.apps, { branch: p.headRef, pr: p.number, sha: p.headSha })
@@ -5856,6 +5877,8 @@ async function startExploration(ctx, a) {
     ...a.useCase ? { useCase: a.useCase } : {},
     ...a.experimental?.length ? { experimental: a.experimental } : {},
     ...a.author ? { author: a.author } : {},
+    ...a.source ? { source: a.source } : {},
+    ...a.agent ? { agent: a.agent } : {},
     startedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
   const gh = await ctx.github().catch(() => null);
@@ -7189,7 +7212,7 @@ async function writeDrafts(ctx, a) {
 }
 
 // src/server.ts
-var VERSION = true ? "0.3.0" : "dev";
+var VERSION = true ? "0.3.1" : "dev";
 var ok = (data) => ({ content: [{ type: "text", text: typeof data === "string" ? data : JSON.stringify(data, null, 2) }] });
 var fail = (e) => ({ content: [{ type: "text", text: `Error: ${e.message ?? String(e)}` }], isError: true });
 var run = (fn) => async (a) => {
@@ -7683,7 +7706,7 @@ function createServer(ctx) {
       },
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
     },
-    run((a) => startExploration(ctx, a))
+    run((a) => startExploration(ctx, { ...a, source: "mcp" }))
   );
   server.registerTool(
     "bridge_list_explorations",

package/dist/explorations.d.ts

@@ -1,4 +1,4 @@
-import { explorationRules, type ExplorationTryIt } from '@bridge-ds/core';
+import { explorationRules, type ExplorationSource, type ExplorationTryIt } from '@bridge-ds/core';
 import { BridgeContext } from './context.js';
 /** `explore/<slug>` from a branch, a slug or a name; throws with how to fix it when it cannot be one. */
 export declare function toExplorationBranch(ref: string): string;
@@ -8,6 +8,9 @@ export interface StartExplorationInput {
     useCase?: string | undefined;
     experimental?: string[] | undefined;
     author?: string | undefined;
+    /** Where it is started from (the MCP tool says mcp, the CLI says cli), and the AI agent behind it when known. */
+    source?: ExplorationSource | undefined;
+    agent?: string | undefined;
     dryRun?: boolean | undefined;
 }
 /**
@@ -106,6 +109,8 @@ export declare function listExplorations(ctx: BridgeContext, a?: {
         status: import("@bridge-ds/core").ExplorationStatus;
         draft: boolean;
         author: string;
+        source?: ExplorationSource | undefined;
+        agent?: string | undefined;
         updatedAt: string;
         headSha: string;
         previews: {
@@ -135,6 +140,8 @@ export declare function listExplorations(ctx: BridgeContext, a?: {
         status: import("@bridge-ds/core").ExplorationStatus;
         draft: boolean;
         author: string;
+        source?: ExplorationSource | undefined;
+        agent?: string | undefined;
         updatedAt: string;
         headSha: string;
         previews: {
@@ -170,6 +177,8 @@ export declare function listExplorations(ctx: BridgeContext, a?: {
         status: import("@bridge-ds/core").ExplorationStatus;
         draft: boolean;
         author: string;
+        source?: ExplorationSource | undefined;
+        agent?: string | undefined;
         updatedAt: string;
         headSha: string;
     })[];

package/dist/index.js

@@ -3,7 +3,7 @@ import {
   VERSION,
   optionsFromArgv,
   serveStdio
-} from "./chunk-GABRGCKY.js";
+} from "./chunk-I3TL76GK.js";
 import "./chunk-X455XY4E.js";
 
 // src/index.ts

package/dist/lib.js

@@ -23,7 +23,7 @@ import {
   parseDocsReply,
   requests_exports,
   serveStdio
-} from "./chunk-GABRGCKY.js";
+} from "./chunk-I3TL76GK.js";
 import {
   CONFIG_FILE,
   loadConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge-ds/mcp",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "description": "Bridge MCP server: lets Claude (Claude Code, Claude Desktop or any MCP client) read, check and propose changes to a DTCG design system repo through pull requests.",
   "license": "MIT",
@@ -54,8 +54,8 @@
     "build:package": "node ../../scripts/build-packages.mjs mcp"
   },
   "dependencies": {
-    "@bridge-ds/core": "^0.3.0",
-    "@bridge-ds/visual": "^0.2.1",
+    "@bridge-ds/core": "^0.4.0",
+    "@bridge-ds/visual": "^0.2.2",
     "@modelcontextprotocol/sdk": "1.31.0",
     "typescript": "5.9.3",
     "zod": "3.25.76"