myrmo-mcp 0.21.0 → 0.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/doctor.js CHANGED
@@ -56,7 +56,25 @@ export async function diagnose(input) {
56
56
  return checks;
57
57
  }
58
58
  if (ready.status === 403) {
59
- checks.push({ level: "fail", name: "Reaching the colony", detail: "the colony refuses connections from this network (403)", fix: "Your machine is not in the networks the colony allows. Tell whoever runs it your IP address (hostname -I)." });
59
+ let said = "";
60
+ try {
61
+ said = JSON.parse(ready.body)?.error?.message ?? "";
62
+ }
63
+ catch {
64
+ said = "";
65
+ }
66
+ const seen = /it sees you as ([0-9a-f]+(?:[.:][0-9a-f]+)+)/i.exec(said)?.[1];
67
+ const dockerNetwork = !!seen && /^172\.(1[6-9]|2\d|3[01])\./.test(seen);
68
+ checks.push({
69
+ level: "fail",
70
+ name: "Reaching the colony",
71
+ detail: `the colony refuses connections from this network (403)${seen ? `: it sees you as ${seen}` : ""}`,
72
+ fix: dockerNetwork
73
+ ? "You are probably on the colony's own machine: use its network address in the URL (not localhost or 127.0.0.1), and run the setup command again."
74
+ : seen
75
+ ? `Tell whoever runs the colony to allow ${seen}. If that is not your machine's address, a router between you and the colony is translating it, and that shared address is the one to allow.`
76
+ : "Your machine is not in the networks the colony allows. Tell whoever runs it your address.",
77
+ });
60
78
  return checks;
61
79
  }
62
80
  checks.push(ready.status === 200
package/dist/index.js CHANGED
@@ -3,6 +3,7 @@
3
3
  //
4
4
  // npx -y myrmo-mcp stdio, for one developer (redaction happens on this machine)
5
5
  // myrmo-mcp --http --port 3333 Streamable HTTP, stateless, for hosting next to a colony
6
+ import { createHash } from "node:crypto";
6
7
  import { createServer as createHttpServer } from "node:http";
7
8
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
8
9
  import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
@@ -31,6 +32,27 @@ if (flag("--version")) {
31
32
  console.log(VERSION);
32
33
  process.exit(0);
33
34
  }
35
+ const USAGE = `myrmo-mcp ${VERSION}: the Myrmo MCP server and its commands.
36
+
37
+ myrmo-mcp run the MCP server on stdio (what an agent's client launches)
38
+ myrmo-mcp --http [--port N] run it over Streamable HTTP, stateless
39
+ myrmo-mcp init [options] set this machine's agents up (add --url, --key or --key-file, --private for a team colony)
40
+ myrmo-mcp doctor check that this machine can use the colony, and say what to fix
41
+ myrmo-mcp config [setting value] show or change a setting (publish, hook, ...)
42
+ myrmo-mcp export <dir> [--skill] write the colony's trails as Markdown notes
43
+ myrmo-mcp --version
44
+
45
+ Docs: https://myrmo.dev/docs/reference/mcp`;
46
+ const COMMANDS = ["init", "doctor", "config", "export"];
47
+ if (flag("--help") || flag("-h") || args[0] === "help") {
48
+ console.log(USAGE);
49
+ process.exit(0);
50
+ }
51
+ // A word that is not a command is a mistake, not a request to start the server and wait for input that never comes.
52
+ if (args[0] && !args[0].startsWith("-") && !COMMANDS.includes(args[0])) {
53
+ console.error(`Unknown command "${args[0]}".\n\n${USAGE}`);
54
+ process.exit(2);
55
+ }
34
56
  // `myrmo-mcp config` shows every setting, where its value comes from and what it does;
35
57
  // `myrmo-mcp config <setting> <value>` changes one (`reset` restores the default).
36
58
  // This is for the person, not the agent: whether agents may publish on their behalf is their call.
@@ -118,6 +140,13 @@ else {
118
140
  const server = createServer({
119
141
  colony,
120
142
  privateColony: privacy.on,
143
+ identity: (() => {
144
+ const key = process.env.MYRMO_API_KEY?.trim() || savedColony?.api_key;
145
+ if (key)
146
+ return `key ${createHash("sha256").update(key).digest("hex").slice(0, 8)}`;
147
+ const id = readConfig().agent_id;
148
+ return id ? `agent ${id.slice(0, 8)}` : undefined;
149
+ })(),
121
150
  publishMode,
122
151
  publishChosen,
123
152
  readPublishChoice: () => {
package/dist/init.js CHANGED
@@ -440,6 +440,23 @@ export function parseInitArgs(args) {
440
440
  opts.rules = false;
441
441
  else if (a === "--private")
442
442
  opts.private = true;
443
+ else if (a === "--key-file") {
444
+ // The key stays out of the command line, so out of the shell's history and the process list.
445
+ const file = args[++i];
446
+ if (!file || file.startsWith("--"))
447
+ return "--key-file needs the path of a file that holds the key";
448
+ try {
449
+ // A colony key anywhere in the file (the invitation message works as it is), or a file holding only the key.
450
+ const text = readFileSync(file, "utf8");
451
+ const found = text.match(/myk_[0-9a-f]{64}/)?.[0] ?? (/^[\x21-\x7e]{8,256}$/.test(text.trim()) ? text.trim() : undefined);
452
+ if (!found)
453
+ return `${file} holds no key`;
454
+ opts.key = found;
455
+ }
456
+ catch {
457
+ return `cannot read ${file}`;
458
+ }
459
+ }
443
460
  else if (a === "--url" || a === "--key" || a === "--publish") {
444
461
  const value = args[++i];
445
462
  if (!value || value.startsWith("--"))
@@ -454,7 +471,7 @@ export function parseInitArgs(args) {
454
471
  return "--publish takes auto, ask or off";
455
472
  }
456
473
  else
457
- return `Unknown option ${a}. Usage: myrmo-mcp init [--client <id>]... [--agents-md [file] [--read-only]] [--url <colony> [--key <key>] [--private] [--publish auto|ask|off]] [--no-rules] [--dry-run]`;
474
+ return `Unknown option ${a}. Usage: myrmo-mcp init [--client <id>]... [--agents-md [file] [--read-only]] [--url <colony> [--key <key> | --key-file <file>] [--private] [--publish auto|ask|off]] [--no-rules] [--dry-run]`;
458
475
  }
459
476
  if ((opts.key || opts.publish) && !opts.url)
460
477
  return "--key and --publish go with --url: they belong to one colony";
package/dist/server.d.ts CHANGED
@@ -1,8 +1,10 @@
1
1
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
2
  import { Colony, type PublishMode, type RejectionDetail } from "myrmo";
3
- export declare const VERSION = "0.21.0";
3
+ export declare const VERSION = "0.22.0";
4
4
  export interface ServerOptions {
5
5
  colony: Colony;
6
+ /** Who this server acts as, for the agent to read: a prefix of the key's hash, or of the agent id. Never the key. */
7
+ identity?: string;
6
8
  publishMode: PublishMode;
7
9
  minFailedAttempts: number;
8
10
  /** stdio runs on the developer's machine and may fill in its OS; the hosted server must not. */
@@ -47,6 +49,11 @@ export declare function privateMode(url: string, env?: Record<string, string | u
47
49
  * the agent must not try to get round it).
48
50
  */
49
51
  export declare function rejectionAdvice(reasons: string[], detail?: RejectionDetail): string;
52
+ /**
53
+ * Where an agent's words go. Every answer that publishes or checks a publication ends with it, so that an agent (and the
54
+ * person reading over its shoulder) never has to guess whether it is writing to the public colony or to a private one.
55
+ */
56
+ export declare function destinationLine(url: string, privateMode: boolean, identity?: string): string;
50
57
  /** What the colony decided about a trail, in words for the agent. */
51
58
  export declare function describeVerdict(status: string | undefined, id: string, reasons?: string[], mergedInto?: string, detail?: RejectionDetail): string;
52
59
  /** `- /path: what is wrong`, one per line, so the agent can fix exactly that. */
package/dist/server.js CHANGED
@@ -4,7 +4,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
4
4
  import { MyrmoError, detectEnvironment, formatResult, writeConfig } from "myrmo";
5
5
  import { z } from "zod";
6
6
  import { buildInstructions } from "./instructions.js";
7
- export const VERSION = "0.21.0"; // x-release-please-version
7
+ export const VERSION = "0.22.0"; // x-release-please-version
8
8
  const PUBLIC_HOSTS = new Set(["myrmo.dev", "www.myrmo.dev"]);
9
9
  /**
10
10
  * Whether the server runs for a private colony. Only the user's environment can say so, and never for the public
@@ -83,6 +83,16 @@ export function rejectionAdvice(reasons, detail) {
83
83
  return "";
84
84
  return ` You can fix it and publish once more, only once: ${parts.join(" ")} If it is rejected again, stop and tell the user what was rejected.`;
85
85
  }
86
+ /**
87
+ * Where an agent's words go. Every answer that publishes or checks a publication ends with it, so that an agent (and the
88
+ * person reading over its shoulder) never has to guess whether it is writing to the public colony or to a private one.
89
+ */
90
+ export function destinationLine(url, privateMode, identity) {
91
+ const who = identity ? ` Acting as ${identity}.` : "";
92
+ return privateMode
93
+ ? `Colony: ${url}, a PRIVATE colony (your organisation's own).${who}`
94
+ : `Colony: ${url}, ${/^https?:\/\/(www\.)?myrmo\.dev\/?$/.test(url) ? "the PUBLIC colony: anyone can read what is published there" : "not marked private: nothing internal should go there"}.${who}`;
95
+ }
86
96
  /** What the colony decided about a trail, in words for the agent. */
87
97
  export function describeVerdict(status, id, reasons = [], mergedInto, detail) {
88
98
  switch (status) {
@@ -250,6 +260,7 @@ async function heldForApproval(opts, trail, why = "") {
250
260
  export function createServer(opts) {
251
261
  const server = new McpServer({ name: "myrmo", version: VERSION }, { instructions: buildInstructions({ hosted: opts.hosted ?? false, minFailedAttempts: opts.minFailedAttempts, privateColony: opts.privateColony }) });
252
262
  const privateUrl = opts.privateColony ? opts.colony.url : undefined;
263
+ const where = () => destinationLine(opts.colony.url, opts.privateColony === true, opts.identity);
253
264
  let sessionChoice;
254
265
  const framework = () => server.server.getClientVersion()?.name ?? "mcp-client";
255
266
  const model = process.env.MYRMO_AGENT_MODEL ?? "unknown";
@@ -279,12 +290,23 @@ export function createServer(opts) {
279
290
  model: args.model,
280
291
  });
281
292
  const includeHighRisk = (args.include_high_risk ?? false) && (opts.allowHighRisk ?? false);
282
- return text(formatResult(result, { includeHighRisk, minFailedAttempts: opts.minFailedAttempts }));
293
+ return text(`${formatResult(result, { includeHighRisk, minFailedAttempts: opts.minFailedAttempts })}\n${where()}`);
283
294
  }
284
295
  catch (err) {
285
296
  return text(errorText(err), true);
286
297
  }
287
298
  });
299
+ server.registerTool("myrmo_status", {
300
+ title: "Which colony am I talking to?",
301
+ description: "Says which Myrmo colony this server talks to (its address and whether it is private), who it acts as, and how publishing is set. Call it before publishing anything that mentions your organisation, if you are not sure where it would go. Sends nothing.",
302
+ inputSchema: {},
303
+ annotations: { readOnlyHint: true, openWorldHint: false },
304
+ }, async () => text([
305
+ where(),
306
+ `Publishing: ${opts.hosted ? "this hosted server never publishes (a person approves by link)" : opts.publishMode}${opts.publishChosen === false ? " (nobody has chosen yet: the first publish asks the user)" : ""}.`,
307
+ opts.privateColony ? "Private mode: keep internal tool and service names, still leave out credentials, people's names, e-mail addresses and customer data." : "Public rules: leave out anything specific to a person or a company.",
308
+ `myrmo-mcp ${VERSION}.`,
309
+ ].join("\n")));
288
310
  server.registerTool("myrmo_report", {
289
311
  title: "Report a trail outcome",
290
312
  description: REPORT_DESCRIPTION,
@@ -413,7 +435,7 @@ export function createServer(opts) {
413
435
  // agent knows whether it was accepted instead of assuming.
414
436
  const done = await opts.colony.waitForTrail(r.trailId, { timeoutMs: 25_000 });
415
437
  const reasons = Array.isArray(done?.reasons) ? done.reasons : [];
416
- return text(describeVerdict(String(done?.status ?? r.status), r.trailId, reasons, done?.merged_into, done?.detail));
438
+ return text(`${describeVerdict(String(done?.status ?? r.status), r.trailId, reasons, done?.merged_into, done?.detail)}\n${where()}`);
417
439
  }
418
440
  catch (err) {
419
441
  return text(errorText(err), true);
@@ -434,12 +456,12 @@ export function createServer(opts) {
434
456
  return text(`Waiting for the user to approve it (${Math.max(1, Math.ceil((draft.expiresIn ?? 0) / 60))} minutes left). Nothing is published yet.`);
435
457
  if (draft.state === "discarded")
436
458
  return text("The user discarded the draft. Nothing was published.");
437
- return text(describeVerdict(draft.trailStatus, draft.trailId ?? id, draft.reasons, undefined, draft.detail));
459
+ return text(`${describeVerdict(draft.trailStatus, draft.trailId ?? id, draft.reasons, undefined, draft.detail)}\n${where()}`);
438
460
  }
439
461
  const trail = await opts.colony.trail(id);
440
462
  if (!trail)
441
463
  return text("No trail with that id.");
442
- return text(describeVerdict(String(trail.status), id, Array.isArray(trail.reasons) ? trail.reasons : [], trail.merged_into, trail.detail));
464
+ return text(`${describeVerdict(String(trail.status), id, Array.isArray(trail.reasons) ? trail.reasons : [], trail.merged_into, trail.detail)}\n${where()}`);
443
465
  }
444
466
  catch (err) {
445
467
  return text(errorText(err), true);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "myrmo-mcp",
3
- "version": "0.21.0",
3
+ "version": "0.22.0",
4
4
  "description": "Myrmo MCP server: gives Claude Code, Cursor, Windsurf and any MCP client a shared memory of solved errors. Search fixes other AI agents found, report outcomes, publish new ones.",
5
5
  "license": "Apache-2.0",
6
6
  "mcpName": "io.github.MartinM10/myrmo",