@looptech-ai/understand-quickly-mcp 0.1.0

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@looptech-ai/understand-quickly-mcp",
+  "version": "0.1.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "description": "Thin MCP server exposing the understand-quickly registry as MCP tools.",
+  "author": "Alex Macdonald-Smith <Alex.Mac@LoopTech.AI>",
+  "contributors": [
+    "LoopTech.AI <https://looptech.ai>"
+  ],
+  "license": "Apache-2.0 AND LicenseRef-Understand-Quickly-Data-License-1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/looptech-ai/understand-quickly.git",
+    "directory": "mcp"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "main": "dist/index.js",
+  "bin": {
+    "understand-quickly-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "test": "tsx --test tests/registry.test.ts tests/tools.test.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^18.19.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+import { listRepos } from "./tools/list-repos.js";
+import { getGraph } from "./tools/get-graph.js";
+import { searchConcepts } from "./tools/search-concepts.js";
+import { findGraphForRepo } from "./tools/find-graph-for-repo.js";
+
+const server = new McpServer(
+  {
+    name: "understand-quickly-mcp",
+    version: "0.1.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  },
+);
+
+function jsonContent(value: unknown) {
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(value, null, 2),
+      },
+    ],
+  };
+}
+
+function errorContent(err: unknown) {
+  const message = err instanceof Error ? err.message : String(err);
+  return {
+    isError: true,
+    content: [{ type: "text" as const, text: message }],
+  };
+}
+
+server.registerTool(
+  "list_repos",
+  {
+    description:
+      "List entries in the understand-quickly registry. Optional filters: format, tag, status.",
+    inputSchema: {
+      format: z
+        .string()
+        .optional()
+        .describe("Exact match on entry.format (e.g. \"understand-anything@1\")."),
+      tag: z
+        .string()
+        .optional()
+        .describe("Returns entries whose tags array contains this string."),
+      status: z
+        .string()
+        .optional()
+        .describe("Exact match on entry.status (typically \"ok\")."),
+    },
+  },
+  async ({ format, tag, status }) => {
+    try {
+      const repos = await listRepos({ format, tag, status });
+      return jsonContent(repos);
+    } catch (err) {
+      return errorContent(err);
+    }
+  },
+);
+
+server.registerTool(
+  "get_graph",
+  {
+    description:
+      "Fetch and return the parsed knowledge graph JSON for a registry entry by id.",
+    inputSchema: {
+      id: z
+        .string()
+        .min(1)
+        .describe("Registry entry id, e.g. \"Lum1104/Understand-Anything\"."),
+    },
+  },
+  async ({ id }) => {
+    try {
+      const graph = await getGraph({ id });
+      return jsonContent(graph);
+    } catch (err) {
+      return errorContent(err);
+    }
+  },
+);
+
+server.registerTool(
+  "search_concepts",
+  {
+    description:
+      "Search aggregated concept terms across the registry. By default reads the precomputed stats.json (single GET, cached 60s) and returns matching terms with sample entry ids. If `id` is given, falls back to a single-graph node search. If stats.json is unavailable, falls back to a capped cross-graph node fan-out.",
+    inputSchema: {
+      query: z.string().min(1).describe("Substring to search for (case-insensitive)."),
+      id: z
+        .string()
+        .optional()
+        .describe(
+          "Optional entry id. If given, scopes the search to that single graph (legacy node-level mode).",
+        ),
+    },
+  },
+  async ({ query, id }) => {
+    try {
+      const result = await searchConcepts({ query, id });
+      return jsonContent(result);
+    } catch (err) {
+      return errorContent(err);
+    }
+  },
+);
+
+server.registerTool(
+  "find_graph_for_repo",
+  {
+    description:
+      "Look up a registry entry by `id` (\"owner/repo\") or `github_url` (https or ssh form, with optional .git/branch/path). Returns graph_url + drift metadata, or {found:false, suggestions} with up to 5 fuzzy-matched ids.",
+    inputSchema: {
+      id: z
+        .string()
+        .regex(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/, {
+          message: "id must be \"owner/repo\".",
+        })
+        .optional()
+        .describe("Registry id, e.g. \"Lum1104/Understand-Anything\"."),
+      github_url: z
+        .string()
+        .min(1)
+        .optional()
+        .describe(
+          "GitHub URL (https or ssh form). Trailing .git, branches, and sub-paths are tolerated.",
+        ),
+    },
+  },
+  async ({ id, github_url }) => {
+    try {
+      if (!id && !github_url) {
+        return errorContent(
+          new Error("Provide at least one of `id` or `github_url`."),
+        );
+      }
+      const result = await findGraphForRepo({ id, github_url });
+      return jsonContent(result);
+    } catch (err) {
+      return errorContent(err);
+    }
+  },
+);
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  // Log to stderr so we don't pollute the JSON-RPC stream on stdout.
+  // eslint-disable-next-line no-console
+  console.error("understand-quickly MCP server ready on stdio");
+}
+
+main().catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error("Fatal MCP server error:", err);
+  process.exit(1);
+});

package/src/registry.ts

@@ -0,0 +1,272 @@
+import { isIP } from "node:net";
+import type {
+  FetchImpl,
+  Registry,
+  RegistryEntry,
+  StatsJson,
+} from "./types.js";
+
+export const DEFAULT_REGISTRY_URL =
+  "https://looptech-ai.github.io/understand-quickly/registry.json";
+export const DEFAULT_STATS_URL =
+  "https://looptech-ai.github.io/understand-quickly/stats.json";
+export const DEFAULT_TTL_MS = 60_000;
+
+interface CacheRecord {
+  fetchedAt: number;
+  registry: Registry;
+}
+
+interface StatsCacheRecord {
+  fetchedAt: number;
+  stats: StatsJson;
+}
+
+// Module-level cache keyed by source URL. Each MCP process gets its own cache;
+// that is fine for a stub server because the registry is small.
+const cache = new Map<string, CacheRecord>();
+const statsCache = new Map<string, StatsCacheRecord>();
+
+export interface LoadRegistryOptions {
+  source?: string;
+  fetchImpl?: FetchImpl;
+  cacheKey?: string;
+  ttlMs?: number;
+  now?: () => number;
+}
+
+/**
+ * Load `registry.json` with a small in-memory TTL cache.
+ *
+ * Pure-ish: all I/O and time goes through injected dependencies, so callers in
+ * tests can drive the cache with a fake fetch and clock.
+ */
+export async function loadRegistry(
+  options: LoadRegistryOptions = {},
+): Promise<Registry> {
+  const source = options.source ?? DEFAULT_REGISTRY_URL;
+  const fetchImpl = options.fetchImpl ?? (globalThis.fetch as unknown as FetchImpl);
+  const cacheKey = options.cacheKey ?? source;
+  const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+  const now = options.now ?? Date.now;
+
+  if (!fetchImpl) {
+    throw new Error(
+      "No fetch implementation available. Pass `fetchImpl` or run on Node 20+.",
+    );
+  }
+
+  const cached = cache.get(cacheKey);
+  if (cached && now() - cached.fetchedAt < ttlMs) {
+    return cached.registry;
+  }
+
+  const response = await fetchImpl(source);
+  if (!response.ok) {
+    // 5xx is transient; if we have a stale cache entry, prefer it over a hard
+    // throw so an upstream Pages outage doesn't take down every MCP client.
+    if (response.status >= 500 && cached) return cached.registry;
+    throw new Error(
+      `Failed to fetch registry from ${source}: ${response.status} ${response.statusText}`,
+    );
+  }
+  const body = (await response.json()) as Registry;
+  if (!body || !Array.isArray(body.entries)) {
+    throw new Error(
+      `Registry at ${source} is malformed: missing \`entries\` array`,
+    );
+  }
+  // Guard against silently consuming a future v2 registry with v1-shaped
+  // tools. The registry's meta.schema.json pins schema_version to const 1; an
+  // older MCP build hitting a newer registry should fail loudly so users know
+  // to upgrade rather than getting half-broken responses.
+  const sv = (body as { schema_version?: unknown }).schema_version;
+  if (sv !== undefined && sv !== 1) {
+    throw new Error(
+      `Registry at ${source} reports schema_version=${String(sv)}; this MCP build supports schema_version=1. Upgrade @looptech-ai/understand-quickly-mcp.`,
+    );
+  }
+  cache.set(cacheKey, { fetchedAt: now(), registry: body });
+  return body;
+}
+
+/** Drop the cached registry for a given key (default: the configured source). */
+export function clearCache(cacheKey?: string): void {
+  if (cacheKey === undefined) {
+    cache.clear();
+    return;
+  }
+  cache.delete(cacheKey);
+}
+
+export interface LoadStatsOptions {
+  source?: string;
+  fetchImpl?: FetchImpl;
+  cacheKey?: string;
+  ttlMs?: number;
+  now?: () => number;
+}
+
+/**
+ * Load `stats.json` with the same TTL caching pattern as `loadRegistry`.
+ *
+ * Validates the minimum shape (schema_version + concepts array). Throws on
+ * non-OK HTTP, malformed body, or missing concepts; callers that want a
+ * fallback path should catch.
+ */
+export async function loadStats(
+  options: LoadStatsOptions = {},
+): Promise<StatsJson> {
+  const source = options.source ?? DEFAULT_STATS_URL;
+  const fetchImpl = options.fetchImpl ?? (globalThis.fetch as unknown as FetchImpl);
+  const cacheKey = options.cacheKey ?? source;
+  const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+  const now = options.now ?? Date.now;
+
+  if (!fetchImpl) {
+    throw new Error(
+      "No fetch implementation available. Pass `fetchImpl` or run on Node 20+.",
+    );
+  }
+
+  const cached = statsCache.get(cacheKey);
+  if (cached && now() - cached.fetchedAt < ttlMs) {
+    return cached.stats;
+  }
+
+  const response = await fetchImpl(source);
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch stats from ${source}: ${response.status} ${response.statusText}`,
+    );
+  }
+  const body = (await response.json()) as StatsJson;
+  if (!body || !Array.isArray(body.concepts)) {
+    throw new Error(
+      `Stats at ${source} is malformed: missing \`concepts\` array`,
+    );
+  }
+  statsCache.set(cacheKey, { fetchedAt: now(), stats: body });
+  return body;
+}
+
+/** Drop the cached stats payload (default: every key). */
+export function clearStatsCache(cacheKey?: string): void {
+  if (cacheKey === undefined) {
+    statsCache.clear();
+    return;
+  }
+  statsCache.delete(cacheKey);
+}
+
+/**
+ * Filter entries with a predicate. Trivial wrapper, but exported so the tool
+ * layer composes via a single named function rather than ad-hoc `.filter`s.
+ */
+export function filterEntries(
+  entries: RegistryEntry[],
+  predicate: (entry: RegistryEntry) => boolean,
+): RegistryEntry[] {
+  return entries.filter(predicate);
+}
+
+/** Resolve the registry URL from env, falling back to the public default. */
+export function resolveRegistrySource(): string {
+  return process.env.UNDERSTAND_QUICKLY_REGISTRY ?? DEFAULT_REGISTRY_URL;
+}
+
+/** Resolve the stats URL from env, falling back to the public default. */
+export function resolveStatsSource(): string {
+  return process.env.UNDERSTAND_QUICKLY_STATS ?? DEFAULT_STATS_URL;
+}
+
+/**
+ * Find an entry by id. Exposed for the `get_graph` and `search_concepts` tools.
+ */
+export function findEntryById(
+  registry: Registry,
+  id: string,
+): RegistryEntry | undefined {
+  return registry.entries.find((entry) => entry.id === id);
+}
+
+// SSRF guard: reject URLs that resolve to private / link-local / loopback /
+// metadata addresses, or that use a non-https scheme. The registry's own
+// schemas pin graph_url to https; this is defence-in-depth for the MCP path,
+// where a malicious registry mirror or a misconfigured URL could otherwise
+// trick this process into fetching cloud-metadata endpoints.
+//
+// Note: this checks the literal hostname, not a resolved IP. Full DNS-rebind
+// protection requires a custom dispatcher; for v0.1 we accept that gap and
+// rely on the surrounding HTTPS-only invariant (TLS makes rebinding harder
+// since the cert must match the literal hostname).
+export function assertSafeFetchUrl(rawUrl: string): URL {
+  let u: URL;
+  try {
+    u = new URL(rawUrl);
+  } catch {
+    throw new Error(`Invalid URL: ${rawUrl}`);
+  }
+  if (u.protocol !== "https:") {
+    throw new Error(`Refusing non-https URL: ${rawUrl}`);
+  }
+  const host = u.hostname.toLowerCase();
+  // Block obvious local / metadata targets by literal hostname.
+  if (
+    host === "localhost" ||
+    host === "0.0.0.0" ||
+    host === "127.0.0.1" ||
+    host === "::1" ||
+    host === "metadata.google.internal" ||
+    host === "metadata" ||
+    host.endsWith(".internal") ||
+    host.endsWith(".local")
+  ) {
+    throw new Error(`Refusing internal host: ${host}`);
+  }
+  // Block IPv4 literals in private/link-local/loopback ranges.
+  const ipKind = isIP(host);
+  if (ipKind === 4) {
+    const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+    if (ipv4) {
+      const [a, b] = ipv4.slice(1).map(Number);
+      if (
+        a === 10 ||
+        a === 127 ||
+        (a === 169 && b === 254) || // link-local incl. AWS/GCP metadata 169.254.169.254
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 168) ||
+        a === 0
+      ) {
+        throw new Error(`Refusing private IPv4 host: ${host}`);
+      }
+    }
+  } else if (ipKind === 6) {
+    // URL.hostname strips the brackets from IPv6 literals (e.g. `fc00::1`,
+    // not `[fc00::1]`), so a startsWith("[") check would never fire. Match
+    // against the normalized address prefix directly.
+    // - fc00::/7 (unique-local) → first hex digit 'f' + second 'c' or 'd'
+    // - fe80::/10 (link-local) → first hex digit 'f' + second 'e' + third 8|9|a|b
+    // - ::1 loopback (caught earlier by literal hostname check)
+    // - ::ffff:0:0/96 IPv4-mapped → defer to Node which will resolve via dual-stack
+    if (/^f[cd]/i.test(host) || /^fe[89ab]/i.test(host)) {
+      throw new Error(`Refusing private IPv6 host: ${host}`);
+    }
+  }
+  return u;
+}
+
+/** Fetch and parse a single graph URL. Used by `get_graph` and `search_concepts`. */
+export async function fetchGraph(
+  graphUrl: string,
+  fetchImpl: FetchImpl = globalThis.fetch as unknown as FetchImpl,
+): Promise<unknown> {
+  assertSafeFetchUrl(graphUrl);
+  const response = await fetchImpl(graphUrl);
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch graph from ${graphUrl}: ${response.status} ${response.statusText}`,
+    );
+  }
+  return response.json();
+}

package/src/tools/find-graph-for-repo.ts

@@ -0,0 +1,221 @@
+import {
+  findEntryById,
+  loadRegistry,
+  resolveRegistrySource,
+} from "../registry.js";
+import type {
+  FetchImpl,
+  FindGraphForRepoParams,
+  RegistryEntry,
+} from "../types.js";
+
+// Registry id pattern: `<owner>/<repo>` with the same character class the
+// site/scripts already use in error messages and validation.
+const ID_PATTERN = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+
+const HTTPS_GITHUB_RE = /^https?:\/\/github\.com\/([^/\s]+)\/([^/\s?#]+)(?:[\/?#].*)?$/i;
+const SSH_GITHUB_RE = /^git@github\.com:([^/\s]+)\/([^/\s?#]+?)(?:\.git)?$/i;
+
+/**
+ * Parse a github URL into a registry id. Accepts:
+ *   - https://github.com/owner/repo
+ *   - https://github.com/owner/repo.git
+ *   - https://github.com/owner/repo/ (trailing slash)
+ *   - https://github.com/owner/repo/tree/branch/...
+ *   - git@github.com:owner/repo.git
+ */
+export function parseGithubUrl(url: string): string | undefined {
+  if (typeof url !== "string" || url.length === 0) return undefined;
+  const trimmed = url.trim();
+
+  const ssh = trimmed.match(SSH_GITHUB_RE);
+  if (ssh) {
+    const owner = ssh[1];
+    const repo = ssh[2].replace(/\.git$/i, "");
+    if (!owner || !repo) return undefined;
+    return `${owner}/${repo}`;
+  }
+
+  const https = trimmed.match(HTTPS_GITHUB_RE);
+  if (https) {
+    const owner = https[1];
+    let repo = https[2];
+    repo = repo.replace(/\.git$/i, "");
+    if (!owner || !repo) return undefined;
+    return `${owner}/${repo}`;
+  }
+
+  return undefined;
+}
+
+/** Levenshtein distance, capped early when it exceeds `maxDistance` for speed. */
+export function levenshtein(a: string, b: string, maxDistance = Infinity): number {
+  if (a === b) return 0;
+  const al = a.length;
+  const bl = b.length;
+  if (al === 0) return bl;
+  if (bl === 0) return al;
+  if (Math.abs(al - bl) > maxDistance) return maxDistance + 1;
+
+  // Two-row DP (rolling).
+  let prev = new Array<number>(bl + 1);
+  let curr = new Array<number>(bl + 1);
+  for (let j = 0; j <= bl; j++) prev[j] = j;
+  for (let i = 1; i <= al; i++) {
+    curr[0] = i;
+    let rowMin = curr[0];
+    for (let j = 1; j <= bl; j++) {
+      const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+      curr[j] = Math.min(
+        curr[j - 1] + 1, // insertion
+        prev[j] + 1, // deletion
+        prev[j - 1] + cost, // substitution
+      );
+      if (curr[j] < rowMin) rowMin = curr[j];
+    }
+    if (rowMin > maxDistance) return maxDistance + 1;
+    [prev, curr] = [curr, prev];
+  }
+  return prev[bl];
+}
+
+function suggestFuzzy(target: string, ids: string[], max = 5, maxDistance = 3): string[] {
+  const targetLower = target.toLowerCase();
+  const scored: Array<{ id: string; dist: number }> = [];
+  for (const id of ids) {
+    const d = levenshtein(targetLower, id.toLowerCase(), maxDistance);
+    if (d <= maxDistance) scored.push({ id, dist: d });
+  }
+  scored.sort((a, b) => a.dist - b.dist || a.id.localeCompare(b.id));
+  return scored.slice(0, max).map((s) => s.id);
+}
+
+function driftSummary(entry: RegistryEntry): string | undefined {
+  const behind = entry.commits_behind;
+  if (typeof behind === "number" && behind > 0) {
+    return `behind by ${behind} commit${behind === 1 ? "" : "s"}`;
+  }
+  if (typeof behind === "number" && behind === 0) {
+    return "up to date";
+  }
+  return undefined;
+}
+
+export interface FindGraphForRepoFoundResult {
+  found: true;
+  id: string;
+  format: string;
+  graph_url: string;
+  status?: string;
+  last_synced?: string;
+  last_sha?: string;
+  source_sha?: string;
+  head_sha?: string;
+  commits_behind?: number;
+  drift_summary?: string;
+}
+
+export interface FindGraphForRepoNotFoundResult {
+  found: false;
+  suggestions: string[];
+}
+
+export type FindGraphForRepoResult =
+  | FindGraphForRepoFoundResult
+  | FindGraphForRepoNotFoundResult;
+
+export interface FindGraphForRepoOptions {
+  fetchImpl?: FetchImpl;
+  source?: string;
+}
+
+export async function findGraphForRepo(
+  params: FindGraphForRepoParams,
+  options: FindGraphForRepoOptions = {},
+): Promise<FindGraphForRepoResult> {
+  const hasId = typeof params?.id === "string" && params.id.length > 0;
+  const hasUrl =
+    typeof params?.github_url === "string" && params.github_url.length > 0;
+
+  if (!hasId && !hasUrl) {
+    throw new Error(
+      "Provide at least one of `id` or `github_url` (e.g. \"owner/repo\" or \"https://github.com/owner/repo\").",
+    );
+  }
+
+  let resolvedId: string | undefined;
+  if (hasId) {
+    if (!ID_PATTERN.test(params.id as string)) {
+      throw new Error(
+        `\`id\` must match \`owner/repo\` (got "${params.id}").`,
+      );
+    }
+    resolvedId = params.id as string;
+  } else if (hasUrl) {
+    const parsed = parseGithubUrl(params.github_url as string);
+    if (!parsed) {
+      throw new Error(
+        `Could not extract owner/repo from \`github_url\`: "${params.github_url}".`,
+      );
+    }
+    if (!ID_PATTERN.test(parsed)) {
+      throw new Error(
+        `Parsed id "${parsed}" does not match \`owner/repo\` pattern.`,
+      );
+    }
+    resolvedId = parsed;
+  }
+
+  const registry = await loadRegistry({
+    source: options.source ?? resolveRegistrySource(),
+    fetchImpl: options.fetchImpl,
+  });
+
+  const entry = findEntryById(registry, resolvedId as string);
+  if (!entry) {
+    const suggestions = suggestFuzzy(
+      resolvedId as string,
+      registry.entries.map((e) => e.id),
+    );
+    return { found: false, suggestions };
+  }
+
+  const out: FindGraphForRepoFoundResult = {
+    found: true,
+    id: entry.id,
+    format: entry.format,
+    graph_url: entry.graph_url,
+  };
+  if (entry.status !== undefined) out.status = entry.status;
+  if (entry.last_synced !== undefined) out.last_synced = entry.last_synced;
+  if (entry.last_sha !== undefined) out.last_sha = entry.last_sha;
+  if (entry.source_sha !== undefined) out.source_sha = entry.source_sha;
+  if (entry.head_sha !== undefined) out.head_sha = entry.head_sha;
+  if (typeof entry.commits_behind === "number") {
+    out.commits_behind = entry.commits_behind;
+  }
+  const drift = driftSummary(entry);
+  if (drift) out.drift_summary = drift;
+  return out;
+}
+
+export const findGraphForRepoToolDefinition = {
+  name: "find_graph_for_repo",
+  description:
+    "Look up a registry entry by `id` (\"owner/repo\") or `github_url` (https or ssh). Returns the entry's graph_url and drift metadata, or `{found:false, suggestions}` with up to 5 fuzzy-matched ids.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      id: {
+        type: "string",
+        description: "Registry id (\"owner/repo\"). At least one of `id` or `github_url` is required.",
+      },
+      github_url: {
+        type: "string",
+        description:
+          "GitHub URL (https or ssh form). Branch/path suffixes and a trailing `.git` are tolerated.",
+      },
+    },
+    additionalProperties: false,
+  },
+};