@pi-archimedes/mcp 2.3.0

package/src/tool-naming.test.ts

@@ -0,0 +1,168 @@
+import { describe, expect, it } from "vitest";
+import {
+  BUILTIN_NAMES,
+  findFormattingCollisions,
+  formatToolName,
+  getServerPrefix,
+  matchRawToolName,
+  resolveServerFromToolName,
+  sanitizeServerPrefix,
+} from "./tool-naming.js";
+
+describe("sanitizeServerPrefix", () => {
+  it("keeps alphanumerics, underscores, and dashes untouched", () => {
+    expect(sanitizeServerPrefix("my-server_1")).toBe("my-server_1");
+  });
+
+  it("hex-encodes disallowed characters with _<hex>_ wrappers", () => {
+    expect(sanitizeServerPrefix("a.b")).toBe("a_2e_b");
+  });
+
+  it("hex-encodes multiple disallowed characters", () => {
+    // "!" = 0x21, "." = 0x2e
+    expect(sanitizeServerPrefix("a!b.c")).toBe("a_21_b_2e_c");
+  });
+});
+
+describe("getServerPrefix", () => {
+  it("server mode sanitizes the raw name", () => {
+    expect(getServerPrefix("my.server", "server")).toBe("my_2e_server");
+  });
+
+  it("none mode returns an empty prefix", () => {
+    expect(getServerPrefix("anything", "none")).toBe("");
+  });
+
+  it("short mode strips a trailing -mcp suffix before sanitizing", () => {
+    expect(getServerPrefix("filesystem-mcp", "short")).toBe("filesystem");
+  });
+
+  it("short mode strips a bare mcp suffix (case-insensitive)", () => {
+    expect(getServerPrefix("GitHubMCP", "short")).toBe("GitHub");
+  });
+
+  it("mcp mode wraps the sanitized name in mcp__", () => {
+    expect(getServerPrefix("my.server", "mcp")).toBe("mcp__my_2e_server");
+  });
+});
+
+describe("formatToolName", () => {
+  it("builds <prefix>_<tool> for server mode", () => {
+    expect(formatToolName("search", "github", "server")).toBe("github_search");
+  });
+
+  it("returns the bare tool name in none mode", () => {
+    expect(formatToolName("search", "github", "none")).toBe("search");
+  });
+
+  it("converts dots in tool names to underscores", () => {
+    expect(formatToolName("a.b.c", "srv", "server")).toBe("srv_a_b_c");
+  });
+
+  it("combines mcp mode with dot conversion", () => {
+    expect(formatToolName("a.b", "fs-mcp", "mcp")).toBe("mcp__fs-mcp_a_b");
+  });
+});
+
+describe("resolveServerFromToolName", () => {
+  it("resolves the owning server", () => {
+    const servers = [
+      { name: "github", prefix: "server" as const },
+      { name: "jira", prefix: "server" as const },
+    ];
+    expect(resolveServerFromToolName("github_search", servers)).toBe("github");
+  });
+
+  it("computes each server's prefix using ITS OWN mode", () => {
+    // In "short" mode, "x-mcp" has prefix "x", so "x_tool" resolves to it.
+    const servers = [{ name: "x-mcp", prefix: "short" as const }];
+    expect(resolveServerFromToolName("x_tool", servers)).toBe("x-mcp");
+    // In "server" mode the same server would be "x-mcp", so "x_tool" must NOT match.
+    const servers2 = [{ name: "x-mcp", prefix: "server" as const }];
+    expect(resolveServerFromToolName("x_tool", servers2)).toBeUndefined();
+  });
+
+  it("longest matching prefix wins", () => {
+    const servers = [
+      { name: "a", prefix: "server" as const },
+      { name: "a_b", prefix: "server" as const },
+    ];
+    // "a_b_x" matches both "a_" (len 1) and "a_b_" (len 3) → "a_b" wins
+    expect(resolveServerFromToolName("a_b_x", servers)).toBe("a_b");
+  });
+
+  it("returns undefined when two servers tie on the longest matching prefix", () => {
+    const servers = [
+      { name: "github", prefix: "server" as const },
+      { name: "github-mcp", prefix: "short" as const }, // also resolves to "github"
+    ];
+    expect(resolveServerFromToolName("github_search", servers)).toBeUndefined();
+  });
+
+  it("returns undefined when no server matches", () => {
+    const servers = [{ name: "github", prefix: "server" as const }];
+    expect(resolveServerFromToolName("read", servers)).toBeUndefined();
+    expect(resolveServerFromToolName("nonesrv_tool", [{ name: "s", prefix: "none" as const }])).toBeUndefined();
+  });
+});
+
+describe("matchRawToolName", () => {
+  it("resolves the raw dotted tool name from its sanitized prefixed name", () => {
+    const tools = [{ name: "a.b" }, { name: "x.y" }, { name: "plain" }];
+    expect(matchRawToolName("srv_a_b", "srv", "server", tools)).toBe("a.b");
+    expect(matchRawToolName("srv_plain", "srv", "server", tools)).toBe("plain");
+  });
+
+  it("uses the server's OWN prefix mode", () => {
+    const tools = [{ name: "a.b" }];
+    // short mode: "github-mcp" → "github"
+    expect(matchRawToolName("github_a_b", "github-mcp", "short", tools)).toBe("a.b");
+    // mcp mode: "mcp__srv"
+    expect(matchRawToolName("mcp__srv_a_b", "srv", "mcp", tools)).toBe("a.b");
+    // none mode: bare (but dot-sanitized) name
+    expect(matchRawToolName("a_b", "srv", "none", tools)).toBe("a.b");
+    // A name formatted under one mode must not match under another
+    expect(matchRawToolName("github_a_b", "github-mcp", "server", tools)).toBeUndefined();
+  });
+
+  it("returns undefined when no tool formats to the given name", () => {
+    expect(matchRawToolName("srv_nope", "srv", "server", [{ name: "a.b" }])).toBeUndefined();
+    expect(matchRawToolName("srv_a_b", "srv", "server", [])).toBeUndefined();
+  });
+});
+
+describe("findFormattingCollisions", () => {
+  it("detects raw names that format to the same final name", () => {
+    const tools = [{ name: "a.b" }, { name: "a_b" }, { name: "plain" }];
+    expect(findFormattingCollisions("srv", "server", tools)).toEqual([
+      { finalName: "srv_a_b", rawNames: ["a.b", "a_b"] },
+    ]);
+  });
+
+  it("returns [] when all formatted names are unique", () => {
+    const tools = [{ name: "a.b" }, { name: "x.y" }, { name: "plain" }];
+    expect(findFormattingCollisions("srv", "server", tools)).toEqual([]);
+  });
+
+  it("detects collisions in none mode (bare sanitized names)", () => {
+    expect(findFormattingCollisions("srv", "none", [{ name: "a.b" }, { name: "a_b" }])).toEqual([
+      { finalName: "a_b", rawNames: ["a.b", "a_b"] },
+    ]);
+  });
+
+  it("excludes raw names that format distinctly from the collision", () => {
+    const tools = [{ name: "a.b" }, { name: "a_b" }, { name: "aB" }];
+    // "aB" formats to "mcp__srv_aB" — NOT part of the collision group
+    expect(findFormattingCollisions("srv", "mcp", tools)).toEqual([
+      { finalName: "mcp__srv_a_b", rawNames: ["a.b", "a_b"] },
+    ]);
+  });
+});
+
+describe("BUILTIN_NAMES", () => {
+  it("contains the pi builtin tool names including mcp", () => {
+    for (const name of ["read", "bash", "edit", "write", "grep", "find", "ls", "mcp"]) {
+      expect(BUILTIN_NAMES.has(name)).toBe(true);
+    }
+  });
+});

package/src/tool-naming.ts

@@ -0,0 +1,114 @@
+import type { ToolPrefix } from "./types.js";
+
+/** Sanitize a server name: keep [A-Za-z0-9_-], replace others with _<hex>_ */
+export function sanitizeServerPrefix(name: string): string {
+  return name.replace(/[^A-Za-z0-9_-]/g, (c) => `_${c.codePointAt(0)!.toString(16)}_`);
+}
+
+export function getServerPrefix(serverName: string, prefix: ToolPrefix): string {
+  switch (prefix) {
+    case "none": return "";
+    case "short": return sanitizeServerPrefix(serverName.replace(/-?mcp$/i, ""));
+    case "mcp": return `mcp__${sanitizeServerPrefix(serverName)}`;
+    case "server":
+    default: return sanitizeServerPrefix(serverName);
+  }
+}
+
+/** Build prefixed tool name: <prefix>_<toolName with . → _> */
+export function formatToolName(toolName: string, serverName: string, prefix: ToolPrefix): string {
+  const p = getServerPrefix(serverName, prefix);
+  const sanitized = toolName.replace(/\./g, "_");
+  return p ? `${p}_${sanitized}` : sanitized;
+}
+
+/**
+ * Inverse: find server owning a prefixed tool name by longest matching prefix.
+ * Returns undefined if no match OR if two servers tie for the longest matching prefix (ambiguous).
+ * IMPORTANT: compute each server's prefix using ITS OWN mode, not a hardcoded "server".
+ */
+export function resolveServerFromToolName(
+  prefixedName: string,
+  servers: Array<{ name: string; prefix: ToolPrefix }>,
+): string | undefined {
+  const matches: Array<{ name: string; prefixLen: number }> = [];
+  for (const { name, prefix } of servers) {
+    const p = getServerPrefix(name, prefix);
+    if (p && prefixedName.startsWith(`${p}_`)) matches.push({ name, prefixLen: p.length });
+  }
+  if (matches.length === 0) return undefined;
+  matches.sort((a, b) => b.prefixLen - a.prefixLen);
+  // Ambiguous if the top two share the winning prefix length
+  if (matches.length > 1 && matches[0]!.prefixLen === matches[1]!.prefixLen) return undefined;
+  return matches[0]!.name;
+}
+
+/**
+ * Group a server's raw tool names by their final formatted name, returning
+ * only the groups with 2+ members. formatToolName is NOT injective: the
+ * `.`→`_` sanitization means e.g. raw names "a.b" and "a_b" both format to
+ * "srv_a_b" — such groups are genuinely ambiguous, and name resolution is
+ * first-match-by-list-order.
+ */
+export function findFormattingCollisions(
+  serverName: string,
+  prefix: ToolPrefix,
+  tools: Array<{ name: string }>,
+): Array<{ finalName: string; rawNames: string[] }> {
+  const byFinal = new Map<string, string[]>();
+  for (const t of tools) {
+    const finalName = formatToolName(t.name, serverName, prefix);
+    const names = byFinal.get(finalName);
+    if (names) names.push(t.name);
+    else byFinal.set(finalName, [t.name]);
+  }
+  return [...byFinal.entries()]
+    .filter(([, rawNames]) => rawNames.length > 1)
+    .map(([finalName, rawNames]) => ({ finalName, rawNames }));
+}
+
+/**
+ * Given a final (possibly prefixed) tool name, find the raw server tool name
+ * that formats to it under the server's own prefix mode. Returns undefined
+ * when no tool formats to the given name (e.g. the tool list is stale) —
+ * callers may then fall back to prefix-stripping, which is only lossless for
+ * dot-free tool names (`a.b` → `a_b` is NOT reversible by slicing).
+ *
+ * NOTE: because formatToolName is not injective ("a.b" and "a_b" format to
+ * the same final name), a matching final name may correspond to MULTIPLE
+ * raw names; the FIRST match in the provided tool list wins, silently. Use
+ * findFormattingCollisions to detect and surface such ambiguity.
+ */
+export function matchRawToolName(
+  finalName: string,
+  serverName: string,
+  prefix: ToolPrefix,
+  tools: Array<{ name: string }>,
+): string | undefined {
+  for (const t of tools) {
+    if (formatToolName(t.name, serverName, prefix) === finalName) return t.name;
+  }
+  return undefined;
+}
+
+/**
+ * Resolve a server reference to a configured server name. Accepts an exact
+ * server name, a final prefixed tool name (delegated to
+ * resolveServerFromToolName), or a bare tool-name prefix (e.g. "github" for
+ * server "github-mcp" under "short" mode).
+ */
+export function resolveServerRef(
+  ref: string,
+  servers: Array<{ name: string; prefix: ToolPrefix }>,
+): string | undefined {
+  const byToolName = resolveServerFromToolName(ref, servers);
+  if (byToolName) return byToolName;
+  // Exact bare-prefix match (only unambiguous single matches are accepted)
+  const exact = servers.filter((s) => getServerPrefix(s.name, s.prefix) === ref);
+  if (exact.length === 1) return exact[0]!.name;
+  return undefined;
+}
+
+export const BUILTIN_NAMES = new Set([
+  "read", "bash", "edit", "write", "grep", "find", "ls", "mcp",
+]);

package/src/types.ts

@@ -0,0 +1,162 @@
+/** Strategy for prefixing exposed tool names */
+export type ToolPrefix = "server" | "none" | "short" | "mcp";
+
+/**
+ * Lifecycle & tooling settings shared by both stdio and HTTP server defs.
+ * These can appear per-server in mcp.json files.
+ */
+export interface SharedServerSettings {
+  /** Connection lifecycle (default: keep-alive) */
+  lifecycle?: "keep-alive" | "lazy" | "lazy-keep-alive" | "eager";
+  /** Idle timeout in minutes; 0 disables */
+  idleTimeout?: number;
+  /** Per-request timeout in milliseconds */
+  requestTimeoutMs?: number;
+  /** Expose direct tools; true = all, string[] = subset of tool names */
+  directTools?: boolean | string[];
+  /** Only expose these tools (whitelist) */
+  includeTools?: string[];
+  /** Never expose these tools (blacklist) */
+  excludeTools?: string[];
+  /** Tool name prefix strategy (default: "server") */
+  toolPrefix?: ToolPrefix;
+  /** Expose resources as a list_resources tool */
+  exposeResources?: boolean;
+  /** Verbose logging for this server */
+  debug?: boolean;
+  /** Pin the MCP protocol version used for this server */
+  protocolVersion?: string;
+}
+
+/** A stdio-based MCP server (spawns a child process) */
+export interface StdioServerDef extends SharedServerSettings {
+  type?: "stdio";
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+  disabled?: boolean;
+}
+
+/** OAuth 2.1 settings for an HTTP MCP server (see plan-026 / ADR 0001) */
+export interface McpOAuthConfig {
+  grantType?: "authorization_code" | "client_credentials"; // default authorization_code
+  clientId?: string;
+  clientSecret?: string; // literal only (no "!command" resolution — see ADR/scope)
+  scope?: string;
+  redirectUri?: string; // pre-registered clients only
+  clientName?: string;
+  authorizationServerUrl?: string;
+}
+
+/** The full set of known `McpOAuthConfig` fields, in no particular order. */
+export const OAUTH_CONFIG_FIELDS = [
+  "grantType",
+  "clientId",
+  "clientSecret",
+  "scope",
+  "redirectUri",
+  "clientName",
+  "authorizationServerUrl",
+] as const;
+
+/** An HTTP-based MCP server (Streamable HTTP or SSE) */
+export interface HttpServerDef extends SharedServerSettings {
+  /** Informational only — the transport is chosen by def shape: a `url` server
+   * connects via StreamableHTTP (with SSE fallback for legacy servers). */
+  type?: "http" | "sse";
+  url: string;
+  /** Bearer token, the "oauth" string (grant-type defaults), or a full OAuth config */
+  auth?: { token: string } | "oauth" | McpOAuthConfig;
+  /** Extra HTTP headers sent with every request */
+  headers?: Record<string, string>;
+  /** Name of an environment variable holding the bearer token */
+  bearerTokenEnv?: string;
+  disabled?: boolean;
+}
+
+export type ServerDef = StdioServerDef | HttpServerDef;
+
+export interface McpFileConfig {
+  mcpServers?: Record<string, ServerDef>;
+  settings?: McpFileSettings;
+}
+
+/** Settings that can appear in the mcp config files (not archimedes.mcp) */
+export interface McpFileSettings {
+  [key: string]: unknown;
+}
+
+/** Settings read from archimedes.mcp in settings.json */
+export interface McpConfig {
+  /** Show direct tools per server in the tool list (default: true) */
+  directTools: boolean;
+  /** Tool name prefix strategy (default: "server") */
+  toolPrefix: ToolPrefix;
+  /** Idle timeout in minutes (default: 10) */
+  idleTimeout: number;
+  /** Warn when a server exposes many direct tools (default: true) */
+  warnOnLargeDirectTools: boolean;
+  /**
+   * When a tool call reaches a server in the `needs-auth` state, trigger the
+   * interactive OAuth flow inline (single entry point: ServerClient
+   * .authenticate) instead of returning guidance to run `/mcp auth`.
+   * (default: false — guidance only)
+   */
+  autoAuth: boolean;
+}
+
+export const DEFAULT_MCP_CONFIG: McpConfig = {
+  directTools: true,
+  toolPrefix: "server",
+  idleTimeout: 10,
+  warnOnLargeDirectTools: true,
+  autoAuth: false,
+};
+
+export const MCP_NAMESPACE = "archimedes.mcp";
+
+/** A single cached tool definition from a server */
+export interface CachedTool {
+  name: string;
+  description?: string;
+  inputSchema: unknown;
+}
+
+/** Cached metadata for one server */
+export interface ServerCacheEntry {
+  /** Hash of the server definition at cache time */
+  configHash: string;
+  tools: CachedTool[];
+  resources: Array<{ uri: string; name?: string; description?: string; mimeType?: string }>;
+  prompts?: Array<{ name: string; description?: string }>;
+  /** Server-level instructions from initialize */
+  instructions?: string;
+  /** Epoch milliseconds when the entry was written */
+  cachedAt: number;
+}
+
+/** Persisted connection outcome for one server (ADR 0004). */
+export interface ServerOutcomeRecord {
+  status: "connected" | "needs-auth" | "error";
+  /** Error text for needs-auth/error outcomes (first line). */
+  error?: string;
+  /** Epoch milliseconds when the outcome was recorded. */
+  at: number;
+}
+
+/** On-disk shape of the metadata cache */
+export interface MetadataCache {
+  version: number;
+  servers: Record<string, ServerCacheEntry>;
+  /**
+   * Last connection outcome per server (ADR 0004). Additive: old cache
+   * files lack the field — a missing key means "not verified", so there is
+   * no CACHE_VERSION bump. `loadMetadataCache` must round-trip it: dropping
+   * the field would silence every `saveServerCache` rewrite.
+   */
+  serverStatuses?: Record<string, ServerOutcomeRecord>;
+}
+
+export const CACHE_VERSION = 1;
+export const CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days