@looptech-ai/understand-quickly-mcp 0.1.0

package/README.md

@@ -0,0 +1,147 @@
+# @looptech-ai/understand-quickly-mcp
+
+A thin [Model Context Protocol](https://modelcontextprotocol.io) server that
+exposes the [understand-quickly](https://looptech-ai.github.io/understand-quickly/)
+registry to any MCP client (Claude Desktop, Codex, Cursor, etc.).
+
+> Status: stub-quality. It works end-to-end but is intentionally minimal —
+> no streaming, no embeddings, no auth.
+
+## What it does
+
+It wraps the public `registry.json` and exposes four tools:
+
+| Tool | Params | Returns |
+| --- | --- | --- |
+| `list_repos` | `{ format?, tag?, status? }` | Array of `{ id, format, description, status, tags, last_synced, graph_url }` |
+| `find_graph_for_repo` | `{ id?, github_url? }` (at least one required) | Single registry entry's graph_url + drift metadata, or `{ found: false, suggestions: [...] }` with up to 5 fuzzy-matched ids |
+| `get_graph` | `{ id }` | Parsed graph JSON for that entry's `graph_url` |
+| `search_concepts` | `{ query, id? }` | Default: aggregated concept matches from the precomputed `stats.json` (single GET, cached 60s). With `id`: substring match across one graph's nodes. Falls back to a capped cross-graph fan-out if `stats.json` is unreachable. |
+
+The registry response is cached in-memory for 60 seconds. `stats.json` uses an
+identical 60-second TTL cache.
+
+### `find_graph_for_repo`
+
+Accepts either an `id` (the registry id, `owner/repo`) or a `github_url`. The
+URL parser tolerates:
+
+- `https://github.com/owner/repo`
+- `https://github.com/owner/repo.git`
+- `https://github.com/owner/repo/` (trailing slash)
+- `https://github.com/owner/repo/tree/main/...` (branch / sub-path)
+- `git@github.com:owner/repo.git`
+
+When the entry is found, the response includes `last_synced`, `last_sha`,
+`source_sha`, `head_sha`, `commits_behind`, and a pretty `drift_summary`
+(e.g. `"behind by 17 commits"`) when those fields are present in the registry.
+
+If the entry is not found, the response is
+`{ found: false, suggestions: [...] }` with up to 5 fuzzy-matched ids
+(Levenshtein distance ≤ 3 against the lowercased id).
+
+### `search_concepts`
+
+By default — that is, when `id` is not provided — `search_concepts` reads the
+precomputed `stats.json` aggregate (a single, cached GET) and returns matching
+concept terms with their entry counts and up to 3 sample registry ids. This
+replaces the previous behaviour, which fanned out up to 5 graph fetches at
+request time.
+
+When `id` is provided, it falls back to the legacy single-graph node search
+(substring match against `id` / `label` / `name`). When `stats.json` is
+unavailable (404 or schema mismatch), it falls back to the capped cross-graph
+fan-out for backward compatibility.
+
+The `source` field on the response indicates which mode served the request:
+`"stats"`, `"graph"`, or `"fanout"`.
+
+## Install
+
+```bash
+cd mcp
+npm install
+npm run build   # compiles TypeScript -> dist/
+npm test        # runs node:test across registry/cache and tool logic
+```
+
+Node 20+ is required (uses the global `fetch`).
+
+## Run locally
+
+For development:
+
+```bash
+npm run dev
+```
+
+For a built binary:
+
+```bash
+npm start
+```
+
+The server speaks stdio JSON-RPC. It will not respond to keystrokes — point an
+MCP client at it.
+
+## Register with Claude Desktop
+
+Add the following to Claude Desktop's `claude_desktop_config.json` (the path is
+`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "understand-quickly": {
+      "command": "npx",
+      "args": [
+        "tsx",
+        "/absolute/path/to/understand-quickly/mcp/src/index.ts"
+      ],
+      "env": {
+        "UNDERSTAND_QUICKLY_REGISTRY": "https://looptech-ai.github.io/understand-quickly/registry.json"
+      }
+    }
+  }
+}
+```
+
+Replace `/absolute/path/to/...` with the actual path to your checkout. Restart
+Claude Desktop after saving.
+
+If you would rather run the compiled output, swap to:
+
+```json
+{
+  "mcpServers": {
+    "understand-quickly": {
+      "command": "node",
+      "args": ["/absolute/path/to/understand-quickly/mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+## Environment variables
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `UNDERSTAND_QUICKLY_REGISTRY` | `https://looptech-ai.github.io/understand-quickly/registry.json` | Override the registry source (e.g. point at a local file or a fork). |
+| `UNDERSTAND_QUICKLY_STATS` | `https://looptech-ai.github.io/understand-quickly/stats.json` | Override the precomputed stats source consumed by `search_concepts`. |
+
+## Current limitations
+
+- **In-memory cache only.** Every server process refetches once a minute. No
+  cross-process or on-disk cache.
+- **Cross-graph fan-out is only a fallback.** When `search_concepts` falls back
+  (no stats.json), it scans only the first 5 `status: ok` entries sequentially.
+- **Substring search is dumb.** No fuzzy matching, no ranking, no embeddings.
+- **No streaming or progress reporting.** Tools block until the upstream
+  responds.
+- **Best-effort node enumeration.** The single-graph fallback assumes the graph
+  has a `nodes` / `entities` / `concepts` / `items` array; otherwise it walks
+  top-level array values.
+- **No retries or backoff** on upstream `graph_url` fetch failures — failed
+  fetches return an empty result for that entry instead of erroring out.
+
+These are all acceptable for an MVP. If you need more, open an issue.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,134 @@
+#!/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) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(value, null, 2),
+            },
+        ],
+    };
+}
+function errorContent(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+        isError: true,
+        content: [{ type: "text", 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);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/registry.d.ts

@@ -0,0 +1,53 @@
+import type { FetchImpl, Registry, RegistryEntry, StatsJson } from "./types.js";
+export declare const DEFAULT_REGISTRY_URL = "https://looptech-ai.github.io/understand-quickly/registry.json";
+export declare const DEFAULT_STATS_URL = "https://looptech-ai.github.io/understand-quickly/stats.json";
+export declare const DEFAULT_TTL_MS = 60000;
+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 declare function loadRegistry(options?: LoadRegistryOptions): Promise<Registry>;
+/** Drop the cached registry for a given key (default: the configured source). */
+export declare function clearCache(cacheKey?: string): void;
+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 declare function loadStats(options?: LoadStatsOptions): Promise<StatsJson>;
+/** Drop the cached stats payload (default: every key). */
+export declare function clearStatsCache(cacheKey?: string): void;
+/**
+ * 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 declare function filterEntries(entries: RegistryEntry[], predicate: (entry: RegistryEntry) => boolean): RegistryEntry[];
+/** Resolve the registry URL from env, falling back to the public default. */
+export declare function resolveRegistrySource(): string;
+/** Resolve the stats URL from env, falling back to the public default. */
+export declare function resolveStatsSource(): string;
+/**
+ * Find an entry by id. Exposed for the `get_graph` and `search_concepts` tools.
+ */
+export declare function findEntryById(registry: Registry, id: string): RegistryEntry | undefined;
+export declare function assertSafeFetchUrl(rawUrl: string): URL;
+/** Fetch and parse a single graph URL. Used by `get_graph` and `search_concepts`. */
+export declare function fetchGraph(graphUrl: string, fetchImpl?: FetchImpl): Promise<unknown>;

package/dist/registry.js

@@ -0,0 +1,191 @@
+import { isIP } from "node:net";
+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;
+// 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();
+const statsCache = new Map();
+/**
+ * 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 = {}) {
+    const source = options.source ?? DEFAULT_REGISTRY_URL;
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    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());
+    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.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) {
+    if (cacheKey === undefined) {
+        cache.clear();
+        return;
+    }
+    cache.delete(cacheKey);
+}
+/**
+ * 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 = {}) {
+    const source = options.source ?? DEFAULT_STATS_URL;
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    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());
+    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) {
+    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, predicate) {
+    return entries.filter(predicate);
+}
+/** Resolve the registry URL from env, falling back to the public default. */
+export function resolveRegistrySource() {
+    return process.env.UNDERSTAND_QUICKLY_REGISTRY ?? DEFAULT_REGISTRY_URL;
+}
+/** Resolve the stats URL from env, falling back to the public default. */
+export function resolveStatsSource() {
+    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, id) {
+    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) {
+    let u;
+    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, fetchImpl = globalThis.fetch) {
+    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();
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}

package/dist/tools/find-graph-for-repo.d.ts

@@ -0,0 +1,53 @@
+import type { FetchImpl, FindGraphForRepoParams } from "../types.js";
+/**
+ * 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 declare function parseGithubUrl(url: string): string | undefined;
+/** Levenshtein distance, capped early when it exceeds `maxDistance` for speed. */
+export declare function levenshtein(a: string, b: string, maxDistance?: number): number;
+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 declare function findGraphForRepo(params: FindGraphForRepoParams, options?: FindGraphForRepoOptions): Promise<FindGraphForRepoResult>;
+export declare const findGraphForRepoToolDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            id: {
+                type: string;
+                description: string;
+            };
+            github_url: {
+                type: string;
+                description: string;
+            };
+        };
+        additionalProperties: boolean;
+    };
+};