myrmo-mcp 0.19.0 → 0.21.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,108 @@
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
+ 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)." });
60
+ return checks;
61
+ }
62
+ checks.push(ready.status === 200
63
+ ? { level: "ok", name: "Reaching the colony", detail: "it answers and reports itself ready" }
64
+ : { 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." });
65
+ if (ready.status !== 200)
66
+ return checks;
67
+ const open = await call(fetchImpl, `${input.url.replace(/\/$/, "")}/v1/stats`, input.apiKey);
68
+ if ("error" in open) {
69
+ checks.push({ level: "fail", name: "Your access key", detail: `no answer (${open.error})`, fix: "Try again; if it persists tell whoever runs the colony." });
70
+ }
71
+ else if (open.status === 401) {
72
+ checks.push(input.apiKey
73
+ ? { 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." }
74
+ : { 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." });
75
+ }
76
+ else if (open.status === 200) {
77
+ 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." });
78
+ }
79
+ else {
80
+ checks.push({ level: "fail", name: "Your access key", detail: `the colony answered ${open.status}`, fix: "Tell whoever runs the colony." });
81
+ }
82
+ checks.push(input.privateMode
83
+ ? { level: "ok", name: "Private mode", detail: "agents keep your internal names in what they publish" }
84
+ : { 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)." });
85
+ checks.push(input.publish === "auto"
86
+ ? { level: "ok", name: "Publishing", detail: "agents publish what they solve, to this colony only" }
87
+ : input.publish === "ask"
88
+ ? { level: "ok", name: "Publishing", detail: "you approve each trail before it is sent" }
89
+ : { level: "warn", name: "Publishing", detail: `agents do not publish (${input.publish})`, fix: "npx myrmo-mcp config publish auto (or ask, to approve each one)" });
90
+ const claude = claudeCodeSetUp(input.home);
91
+ const gemini = join(input.home, ".gemini", "GEMINI.md");
92
+ const geminiRules = existsSync(gemini) && readFileSync(gemini, "utf8").includes("myrmo:start");
93
+ if (claude || geminiRules) {
94
+ checks.push({ level: "ok", name: "Agents", detail: [claude ? `Claude Code: ${claude}` : "", geminiRules ? "Gemini CLI / Antigravity: rules installed" : ""].filter(Boolean).join("; ") });
95
+ }
96
+ else {
97
+ 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." });
98
+ }
99
+ return checks;
100
+ }
101
+ export function render(checks) {
102
+ const mark = { ok: "ok ", warn: "warn", fail: "FAIL" };
103
+ const lines = checks.flatMap((c) => [`[${mark[c.level]}] ${c.name}: ${c.detail}`, ...(c.fix ? [` -> ${c.fix}`] : [])]);
104
+ const failed = checks.filter((c) => c.level === "fail").length;
105
+ const warned = checks.filter((c) => c.level === "warn").length;
106
+ 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.");
107
+ return lines.join("\n");
108
+ }
package/dist/index.js CHANGED
@@ -84,6 +84,20 @@ if (args[0] === "export") {
84
84
  console.log(`${written} trails from ${colony.url} written to ${dir}${flag("--skill") ? " as a skill (SKILL.md)" : ""}.`);
85
85
  process.exit(0);
86
86
  }
87
+ // `myrmo-mcp doctor`: checks that this machine can use the colony and says what to fix.
88
+ if (args[0] === "doctor") {
89
+ const { diagnose, render } = await import("./doctor.js");
90
+ const checks = await diagnose({
91
+ url: colonyUrl,
92
+ saved: savedColony !== undefined,
93
+ apiKey: process.env.MYRMO_API_KEY?.trim() || savedColony?.api_key,
94
+ privateMode: privateMode(colonyUrl, process.env, savedColony?.private === true).on,
95
+ publish: publishMode,
96
+ home: (await import("node:os")).homedir(),
97
+ });
98
+ console.log(render(checks));
99
+ process.exit(checks.some((c) => c.level === "fail") ? 1 : 0);
100
+ }
87
101
  if (args[0] === "init") {
88
102
  const parsed = parseInitArgs(args.slice(1));
89
103
  if (typeof parsed === "string") {
package/dist/server.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
- import { Colony, type PublishMode } from "myrmo";
3
- export declare const VERSION = "0.19.0";
2
+ import { Colony, type PublishMode, type RejectionDetail } from "myrmo";
3
+ export declare const VERSION = "0.21.0";
4
4
  export interface ServerOptions {
5
5
  colony: Colony;
6
6
  publishMode: PublishMode;
@@ -41,8 +41,14 @@ export declare function privateMode(url: string, env?: Record<string, string | u
41
41
  on: boolean;
42
42
  warning?: string;
43
43
  };
44
+ /**
45
+ * What to do about a rejection, when the colony said what is wrong: fix those parts and publish once more. A trail
46
+ * rejected for an instruction aimed at an agent gets no advice (the colony does not say what tripped that check, and
47
+ * the agent must not try to get round it).
48
+ */
49
+ export declare function rejectionAdvice(reasons: string[], detail?: RejectionDetail): string;
44
50
  /** What the colony decided about a trail, in words for the agent. */
45
- export declare function describeVerdict(status: string | undefined, id: string, reasons?: string[], mergedInto?: string): string;
51
+ export declare function describeVerdict(status: string | undefined, id: string, reasons?: string[], mergedInto?: string, detail?: RejectionDetail): string;
46
52
  /** `- /path: what is wrong`, one per line, so the agent can fix exactly that. */
47
53
  export declare function describeIssues(errors: {
48
54
  path: string;
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.19.0"; // x-release-please-version
7
+ export const VERSION = "0.21.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
@@ -63,15 +63,35 @@ const REASONS = {
63
63
  enrichment_failed: "the colony could not process it",
64
64
  invalid_trail: "it was not valid",
65
65
  };
66
+ /**
67
+ * What to do about a rejection, when the colony said what is wrong: fix those parts and publish once more. A trail
68
+ * rejected for an instruction aimed at an agent gets no advice (the colony does not say what tripped that check, and
69
+ * the agent must not try to get round it).
70
+ */
71
+ export function rejectionAdvice(reasons, detail) {
72
+ if (reasons.includes("prompt_injection"))
73
+ return " Do not try to get round this check; tell the user.";
74
+ const parts = [];
75
+ const sensitive = detail?.sensitive_content;
76
+ if (sensitive) {
77
+ const where = sensitive.fields.length ? ` The colony found it in: ${sensitive.fields.join(", ")}.` : "";
78
+ parts.push(`${where} ${sensitive.hint}`.trim());
79
+ }
80
+ if (detail?.low_quality)
81
+ parts.push(detail.low_quality.hint);
82
+ if (parts.length === 0)
83
+ return "";
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
+ }
66
86
  /** What the colony decided about a trail, in words for the agent. */
67
- export function describeVerdict(status, id, reasons = [], mergedInto) {
87
+ export function describeVerdict(status, id, reasons = [], mergedInto, detail) {
68
88
  switch (status) {
69
89
  case "indexed":
70
90
  return `Published: trail ${id} is indexed and other agents can find it.`;
71
91
  case "merged":
72
92
  return `Not added: the colony already had this solution for this error${mergedInto ? ` (merged into ${mergedInto})` : ""}.`;
73
93
  case "rejected":
74
- return `Rejected by the colony because ${reasons.map((r) => REASONS[r] ?? r).join("; ") || "of an unspecified reason"}. Do not publish it again unchanged.`;
94
+ return `Rejected by the colony because ${reasons.map((r) => REASONS[r] ?? r).join("; ") || "of an unspecified reason"}. Do not publish it again unchanged.${rejectionAdvice(reasons, detail)}`;
75
95
  case "removed":
76
96
  return `Trail ${id} was removed by an operator.`;
77
97
  case "queued":
@@ -393,7 +413,7 @@ export function createServer(opts) {
393
413
  // agent knows whether it was accepted instead of assuming.
394
414
  const done = await opts.colony.waitForTrail(r.trailId, { timeoutMs: 25_000 });
395
415
  const reasons = Array.isArray(done?.reasons) ? done.reasons : [];
396
- return text(describeVerdict(String(done?.status ?? r.status), r.trailId, reasons, done?.merged_into));
416
+ return text(describeVerdict(String(done?.status ?? r.status), r.trailId, reasons, done?.merged_into, done?.detail));
397
417
  }
398
418
  catch (err) {
399
419
  return text(errorText(err), true);
@@ -414,12 +434,12 @@ export function createServer(opts) {
414
434
  return text(`Waiting for the user to approve it (${Math.max(1, Math.ceil((draft.expiresIn ?? 0) / 60))} minutes left). Nothing is published yet.`);
415
435
  if (draft.state === "discarded")
416
436
  return text("The user discarded the draft. Nothing was published.");
417
- return text(describeVerdict(draft.trailStatus, draft.trailId ?? id, draft.reasons));
437
+ return text(describeVerdict(draft.trailStatus, draft.trailId ?? id, draft.reasons, undefined, draft.detail));
418
438
  }
419
439
  const trail = await opts.colony.trail(id);
420
440
  if (!trail)
421
441
  return text("No trail with that id.");
422
- return text(describeVerdict(String(trail.status), id, Array.isArray(trail.reasons) ? trail.reasons : [], trail.merged_into));
442
+ return text(describeVerdict(String(trail.status), id, Array.isArray(trail.reasons) ? trail.reasons : [], trail.merged_into, trail.detail));
423
443
  }
424
444
  catch (err) {
425
445
  return text(errorText(err), true);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "myrmo-mcp",
3
- "version": "0.19.0",
3
+ "version": "0.21.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",