myrmo-mcp 0.20.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.
@@ -0,0 +1,21 @@
1
+ export type Level = "ok" | "warn" | "fail";
2
+ export interface Check {
3
+ level: Level;
4
+ name: string;
5
+ detail: string;
6
+ /** What to try, when the level is not ok. */
7
+ fix?: string;
8
+ }
9
+ export interface DoctorInput {
10
+ url: string;
11
+ /** True when the URL is the one `init --url` saved, so that its key and mode apply. */
12
+ saved: boolean;
13
+ apiKey?: string;
14
+ privateMode: boolean;
15
+ publish: string;
16
+ nodeVersion?: string;
17
+ home: string;
18
+ fetchImpl?: typeof fetch;
19
+ }
20
+ export declare function diagnose(input: DoctorInput): Promise<Check[]>;
21
+ export declare function render(checks: Check[]): string;
package/dist/doctor.js ADDED
@@ -0,0 +1,126 @@
1
+ // `myrmo-mcp doctor`: is this machine set up to use the colony, and if not, what to do. For the person, not the agent.
2
+ // Every check says what it found and, when it fails, the one thing to try. Nothing is changed and no text of any
3
+ // trail is read: it asks the colony whether it is up, whether it lets this network in and whether this key opens it.
4
+ import { existsSync, readFileSync } from "node:fs";
5
+ import { join } from "node:path";
6
+ import { claudeCodeSetUp } from "./init.js";
7
+ const PUBLIC_HOSTS = new Set(["myrmo.dev", "www.myrmo.dev"]);
8
+ async function call(fetchImpl, url, key) {
9
+ try {
10
+ const res = await fetchImpl(url, {
11
+ headers: { accept: "application/json", "user-agent": "myrmo-mcp-doctor", ...(key ? { authorization: `Bearer ${key}` } : {}) },
12
+ signal: AbortSignal.timeout(6000),
13
+ });
14
+ return { status: res.status, body: (await res.text()).slice(0, 300) };
15
+ }
16
+ catch (err) {
17
+ const cause = err.cause?.code ?? err.name;
18
+ return { error: String(cause) };
19
+ }
20
+ }
21
+ export async function diagnose(input) {
22
+ const checks = [];
23
+ const fetchImpl = input.fetchImpl ?? fetch;
24
+ const major = Number((input.nodeVersion ?? process.versions.node).split(".")[0]);
25
+ checks.push(major >= 20
26
+ ? { level: "ok", name: "Node.js", detail: `version ${input.nodeVersion ?? process.versions.node}` }
27
+ : { level: "fail", name: "Node.js", detail: `version ${input.nodeVersion ?? process.versions.node} is too old`, fix: "Install Node.js 20 or newer (node --version) and run the command again." });
28
+ let host = "";
29
+ try {
30
+ host = new URL(input.url).host;
31
+ }
32
+ catch {
33
+ checks.push({ level: "fail", name: "Colony address", detail: `"${input.url}" is not a web address`, fix: "Run the setup command again with --url http://<machine>:8080." });
34
+ return checks;
35
+ }
36
+ const isPublic = PUBLIC_HOSTS.has(host);
37
+ checks.push({
38
+ level: isPublic ? "warn" : "ok",
39
+ name: "Colony",
40
+ detail: `${input.url}${isPublic ? " (the public colony)" : input.saved ? " (saved by init)" : " (from MYRMO_URL)"}`,
41
+ fix: isPublic ? "To use your team's colony, run the setup command you were sent (npx myrmo-mcp init --url ... --key ... --private)." : undefined,
42
+ });
43
+ if (isPublic)
44
+ return checks;
45
+ const ready = await call(fetchImpl, `${input.url.replace(/\/$/, "")}/readyz`);
46
+ if ("error" in ready) {
47
+ const refused = ready.error === "ECONNREFUSED";
48
+ checks.push({
49
+ level: "fail",
50
+ name: "Reaching the colony",
51
+ detail: refused ? "the machine answered but nothing listens on that port" : `no answer (${ready.error})`,
52
+ fix: refused
53
+ ? "Ask whoever runs the colony whether it is up (bash deploy/private-colony.sh status on its machine)."
54
+ : "Check that you are on the team's network and that the address and port are right; from this machine try: curl " + input.url + "/readyz",
55
+ });
56
+ return checks;
57
+ }
58
+ if (ready.status === 403) {
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
+ });
78
+ return checks;
79
+ }
80
+ checks.push(ready.status === 200
81
+ ? { level: "ok", name: "Reaching the colony", detail: "it answers and reports itself ready" }
82
+ : { level: "fail", name: "Reaching the colony", detail: `it answered ${ready.status}`, fix: "It is up but not ready (it may still be starting). Try again in a minute, then tell whoever runs it." });
83
+ if (ready.status !== 200)
84
+ return checks;
85
+ const open = await call(fetchImpl, `${input.url.replace(/\/$/, "")}/v1/stats`, input.apiKey);
86
+ if ("error" in open) {
87
+ checks.push({ level: "fail", name: "Your access key", detail: `no answer (${open.error})`, fix: "Try again; if it persists tell whoever runs the colony." });
88
+ }
89
+ else if (open.status === 401) {
90
+ checks.push(input.apiKey
91
+ ? { level: "fail", name: "Your access key", detail: "the colony does not accept it (401)", fix: "The key was copied wrong or has been revoked. Ask for a new one and run the setup command again." }
92
+ : { level: "fail", name: "Your access key", detail: "this colony needs a key and none is set", fix: "Run the setup command you were sent: npx myrmo-mcp init --url <colony> --key <your key> --private --publish auto." });
93
+ }
94
+ else if (open.status === 200) {
95
+ checks.push(input.apiKey ? { level: "ok", name: "Your access key", detail: "accepted" } : { level: "warn", name: "Your access key", detail: "this colony does not ask for a key", fix: "If it should be private, tell whoever runs it." });
96
+ }
97
+ else {
98
+ checks.push({ level: "fail", name: "Your access key", detail: `the colony answered ${open.status}`, fix: "Tell whoever runs the colony." });
99
+ }
100
+ checks.push(input.privateMode
101
+ ? { level: "ok", name: "Private mode", detail: "agents keep your internal names in what they publish" }
102
+ : { level: "warn", name: "Private mode", detail: "off: agents would strip internal names from what they publish", fix: "Run the setup command again with --private (or set MYRMO_PRIVATE=1)." });
103
+ checks.push(input.publish === "auto"
104
+ ? { level: "ok", name: "Publishing", detail: "agents publish what they solve, to this colony only" }
105
+ : input.publish === "ask"
106
+ ? { level: "ok", name: "Publishing", detail: "you approve each trail before it is sent" }
107
+ : { level: "warn", name: "Publishing", detail: `agents do not publish (${input.publish})`, fix: "npx myrmo-mcp config publish auto (or ask, to approve each one)" });
108
+ const claude = claudeCodeSetUp(input.home);
109
+ const gemini = join(input.home, ".gemini", "GEMINI.md");
110
+ const geminiRules = existsSync(gemini) && readFileSync(gemini, "utf8").includes("myrmo:start");
111
+ if (claude || geminiRules) {
112
+ checks.push({ level: "ok", name: "Agents", detail: [claude ? `Claude Code: ${claude}` : "", geminiRules ? "Gemini CLI / Antigravity: rules installed" : ""].filter(Boolean).join("; ") });
113
+ }
114
+ else {
115
+ checks.push({ level: "fail", name: "Agents", detail: "no agent on this machine is set up to use Myrmo", fix: "Run the setup command again, then restart Claude Code or Antigravity." });
116
+ }
117
+ return checks;
118
+ }
119
+ export function render(checks) {
120
+ const mark = { ok: "ok ", warn: "warn", fail: "FAIL" };
121
+ const lines = checks.flatMap((c) => [`[${mark[c.level]}] ${c.name}: ${c.detail}`, ...(c.fix ? [` -> ${c.fix}`] : [])]);
122
+ const failed = checks.filter((c) => c.level === "fail").length;
123
+ const warned = checks.filter((c) => c.level === "warn").length;
124
+ lines.push("", failed ? `${failed} problem${failed > 1 ? "s" : ""} to fix, then run this again.` : warned ? "Works, with things worth a look." : "Everything is in place. Restart your agent if you have not since the setup.");
125
+ return lines.join("\n");
126
+ }
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.
@@ -84,6 +106,20 @@ if (args[0] === "export") {
84
106
  console.log(`${written} trails from ${colony.url} written to ${dir}${flag("--skill") ? " as a skill (SKILL.md)" : ""}.`);
85
107
  process.exit(0);
86
108
  }
109
+ // `myrmo-mcp doctor`: checks that this machine can use the colony and says what to fix.
110
+ if (args[0] === "doctor") {
111
+ const { diagnose, render } = await import("./doctor.js");
112
+ const checks = await diagnose({
113
+ url: colonyUrl,
114
+ saved: savedColony !== undefined,
115
+ apiKey: process.env.MYRMO_API_KEY?.trim() || savedColony?.api_key,
116
+ privateMode: privateMode(colonyUrl, process.env, savedColony?.private === true).on,
117
+ publish: publishMode,
118
+ home: (await import("node:os")).homedir(),
119
+ });
120
+ console.log(render(checks));
121
+ process.exit(checks.some((c) => c.level === "fail") ? 1 : 0);
122
+ }
87
123
  if (args[0] === "init") {
88
124
  const parsed = parseInitArgs(args.slice(1));
89
125
  if (typeof parsed === "string") {
@@ -104,6 +140,13 @@ else {
104
140
  const server = createServer({
105
141
  colony,
106
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
+ })(),
107
150
  publishMode,
108
151
  publishChosen,
109
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.20.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.20.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.20.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",