@looptech-ai/understand-quickly-mcp 0.1.0

package/src/tools/get-graph.ts

@@ -0,0 +1,36 @@
+import {
+  fetchGraph,
+  findEntryById,
+  loadRegistry,
+  resolveRegistrySource,
+} from "../registry.js";
+import type { GetGraphParams } from "../types.js";
+
+export async function getGraph(params: GetGraphParams): Promise<unknown> {
+  if (!params || typeof params.id !== "string" || params.id.length === 0) {
+    throw new Error("`id` is required");
+  }
+  const registry = await loadRegistry({ source: resolveRegistrySource() });
+  const entry = findEntryById(registry, params.id);
+  if (!entry) {
+    throw new Error(`No registry entry found with id "${params.id}"`);
+  }
+  return fetchGraph(entry.graph_url);
+}
+
+export const getGraphToolDefinition = {
+  name: "get_graph",
+  description:
+    "Fetch and return the parsed knowledge graph JSON for a registry entry by id.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      id: {
+        type: "string",
+        description: "Registry entry id, e.g. \"Lum1104/Understand-Anything\".",
+      },
+    },
+    required: ["id"],
+    additionalProperties: false,
+  },
+};

package/src/tools/list-repos.ts

@@ -0,0 +1,62 @@
+import {
+  filterEntries,
+  loadRegistry,
+  resolveRegistrySource,
+} from "../registry.js";
+import type {
+  ListReposParams,
+  RegistryEntry,
+  RepoSummary,
+} from "../types.js";
+
+function toSummary(entry: RegistryEntry): RepoSummary {
+  return {
+    id: entry.id,
+    format: entry.format,
+    description: entry.description,
+    status: entry.status,
+    tags: entry.tags,
+    last_synced: entry.last_synced,
+    graph_url: entry.graph_url,
+  };
+}
+
+export async function listRepos(
+  params: ListReposParams = {},
+): Promise<RepoSummary[]> {
+  const registry = await loadRegistry({ source: resolveRegistrySource() });
+  const filtered = filterEntries(registry.entries, (entry) => {
+    if (params.format && entry.format !== params.format) return false;
+    if (params.status && entry.status !== params.status) return false;
+    if (params.tag) {
+      const tags = entry.tags ?? [];
+      if (!tags.includes(params.tag)) return false;
+    }
+    return true;
+  });
+  return filtered.map(toSummary);
+}
+
+export const listReposToolDefinition = {
+  name: "list_repos",
+  description:
+    "List entries in the understand-quickly registry. Optional filters: `format`, `tag`, `status`.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      format: {
+        type: "string",
+        description: "Exact match on entry.format (e.g. \"understand-anything@1\").",
+      },
+      tag: {
+        type: "string",
+        description: "Returns entries whose `tags` array contains this string.",
+      },
+      status: {
+        type: "string",
+        description: "Exact match on entry.status (typically \"ok\").",
+      },
+    },
+    additionalProperties: false,
+  },
+};

package/src/tools/search-concepts.ts

@@ -0,0 +1,239 @@
+import {
+  fetchGraph,
+  findEntryById,
+  loadRegistry,
+  loadStats,
+  resolveRegistrySource,
+  resolveStatsSource,
+} from "../registry.js";
+import type {
+  FetchImpl,
+  RegistryEntry,
+  SearchConceptsParams,
+  SearchHit,
+  StatsConcept,
+} from "../types.js";
+
+// Stub-quality cap on cross-graph searches. A real implementation would either
+// stream results or build a server-side index — for now we just bound the work.
+const CROSS_GRAPH_LIMIT = 5;
+const CONCEPTS_RESULT_CAP = 50;
+const SAMPLES_CAP = 3;
+
+interface NodeLike {
+  id?: unknown;
+  label?: unknown;
+  name?: unknown;
+  [key: string]: unknown;
+}
+
+/**
+ * Best-effort node enumeration. Different graph formats nest nodes differently
+ * (`nodes`, `entities`, `concepts`, …). For the stub we accept any of those
+ * common shapes and fall back to walking the top-level object's array values.
+ */
+function collectNodes(graph: unknown): NodeLike[] {
+  if (!graph || typeof graph !== "object") return [];
+  const obj = graph as Record<string, unknown>;
+  const candidates = ["nodes", "entities", "concepts", "items"];
+  for (const key of candidates) {
+    const value = obj[key];
+    if (Array.isArray(value)) {
+      return value.filter(
+        (item): item is NodeLike => !!item && typeof item === "object",
+      );
+    }
+  }
+  // Fallback: pull every array value and concat.
+  const collected: NodeLike[] = [];
+  for (const value of Object.values(obj)) {
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (item && typeof item === "object") collected.push(item as NodeLike);
+      }
+    }
+  }
+  return collected;
+}
+
+function matchNode(node: NodeLike, query: string): SearchHit | undefined {
+  const lower = query.toLowerCase();
+  const fields: Array<["id" | "label" | "name", unknown]> = [
+    ["id", node.id],
+    ["label", node.label],
+    ["name", node.name],
+  ];
+  for (const [field, raw] of fields) {
+    if (typeof raw === "string" && raw.toLowerCase().includes(lower)) {
+      return {
+        node_id: typeof node.id === "string" ? node.id : undefined,
+        label: typeof node.label === "string" ? node.label : undefined,
+        name: typeof node.name === "string" ? node.name : undefined,
+        matched_field: field,
+        matched_value: raw,
+      };
+    }
+  }
+  return undefined;
+}
+
+async function searchOneGraph(
+  graphUrl: string,
+  query: string,
+  fetchImpl?: FetchImpl,
+): Promise<SearchHit[]> {
+  let graph: unknown;
+  try {
+    graph = await fetchGraph(graphUrl, fetchImpl);
+  } catch (err) {
+    // For the stub, swallow per-graph fetch errors so a single 404 does not
+    // poison the whole result set.
+    return [];
+  }
+  const nodes = collectNodes(graph);
+  const hits: SearchHit[] = [];
+  for (const node of nodes) {
+    const hit = matchNode(node, query);
+    if (hit) hits.push(hit);
+  }
+  return hits;
+}
+
+export interface SearchConceptsResult {
+  query: string;
+  // Single-graph mode (id given) or fan-out fallback mode.
+  results?: Array<{
+    id: string;
+    graph_url: string;
+    hits: SearchHit[];
+  }>;
+  // stats.json-backed mode (default).
+  matches?: Array<{
+    term: string;
+    count: number;
+    entries: number;
+    samples: string[];
+  }>;
+  source: "stats" | "graph" | "fanout";
+  truncated?: boolean;
+  scanned?: number;
+}
+
+export interface SearchConceptsOptions {
+  fetchImpl?: FetchImpl;
+  registrySource?: string;
+  statsSource?: string;
+}
+
+async function fanoutSearch(
+  query: string,
+  fetchImpl: FetchImpl | undefined,
+  registrySource: string,
+): Promise<SearchConceptsResult> {
+  const registry = await loadRegistry({ source: registrySource, fetchImpl });
+  const okEntries: RegistryEntry[] = registry.entries.filter(
+    (entry) => entry.status === "ok",
+  );
+  const slice = okEntries.slice(0, CROSS_GRAPH_LIMIT);
+  const results: NonNullable<SearchConceptsResult["results"]> = [];
+  // Sequential to keep the stub gentle on remote hosts.
+  for (const entry of slice) {
+    const hits = await searchOneGraph(entry.graph_url, query, fetchImpl);
+    if (hits.length > 0) {
+      results.push({ id: entry.id, graph_url: entry.graph_url, hits });
+    }
+  }
+  return {
+    query,
+    source: "fanout",
+    scanned: slice.length,
+    truncated: okEntries.length > slice.length,
+    results,
+  };
+}
+
+function searchStatsConcepts(
+  query: string,
+  concepts: StatsConcept[],
+): SearchConceptsResult["matches"] {
+  const lower = query.toLowerCase();
+  const out: NonNullable<SearchConceptsResult["matches"]> = [];
+  for (const c of concepts) {
+    if (typeof c?.term !== "string") continue;
+    if (!c.term.toLowerCase().includes(lower)) continue;
+    out.push({
+      term: c.term,
+      count: c.entries,
+      entries: c.entries,
+      samples: Array.isArray(c.samples) ? c.samples.slice(0, SAMPLES_CAP) : [],
+    });
+    if (out.length >= CONCEPTS_RESULT_CAP) break;
+  }
+  return out;
+}
+
+export async function searchConcepts(
+  params: SearchConceptsParams,
+  options: SearchConceptsOptions = {},
+): Promise<SearchConceptsResult> {
+  if (!params || typeof params.query !== "string" || params.query.length === 0) {
+    throw new Error("`query` is required");
+  }
+  const registrySource = options.registrySource ?? resolveRegistrySource();
+  const statsSource = options.statsSource ?? resolveStatsSource();
+  const fetchImpl = options.fetchImpl;
+
+  // Single-graph mode: keep the legacy fan-out behavior for one specific graph
+  // since stats.json is repo-keyed by sample only and is not a substitute.
+  if (params.id) {
+    const registry = await loadRegistry({ source: registrySource, fetchImpl });
+    const entry = findEntryById(registry, params.id);
+    if (!entry) {
+      throw new Error(`No registry entry found with id "${params.id}"`);
+    }
+    const hits = await searchOneGraph(entry.graph_url, params.query, fetchImpl);
+    return {
+      query: params.query,
+      source: "graph",
+      scanned: 1,
+      results: [{ id: entry.id, graph_url: entry.graph_url, hits }],
+    };
+  }
+
+  // Default: stats.json-backed concept search. Cheap (one GET, cached 60s).
+  try {
+    const stats = await loadStats({ source: statsSource, fetchImpl });
+    const matches = searchStatsConcepts(params.query, stats.concepts);
+    return {
+      query: params.query,
+      source: "stats",
+      matches,
+    };
+  } catch (err) {
+    // Fall through to the legacy fan-out so an outage on stats.json does not
+    // break this tool entirely.
+    return fanoutSearch(params.query, fetchImpl, registrySource);
+  }
+}
+
+export const searchConceptsToolDefinition = {
+  name: "search_concepts",
+  description:
+    "Search aggregated concept terms (default: precomputed `stats.json`). Pass `id` to fall back to a single-graph node search. If `stats.json` is unavailable, falls back to a capped cross-graph node fan-out.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      query: {
+        type: "string",
+        description: "Substring to search for (case-insensitive).",
+      },
+      id: {
+        type: "string",
+        description:
+          "Optional entry id. If given, scopes the search to that single graph (legacy node-level mode).",
+      },
+    },
+    required: ["query"],
+    additionalProperties: false,
+  },
+};

package/src/types.ts

@@ -0,0 +1,101 @@
+// Types for the understand-quickly registry. The live schema is owned by the
+// parent project under `schemas/`; we duplicate just the surface this MCP
+// server consumes. Anything we do not use is typed as `unknown` so that we
+// stay forward-compatible with future schema additions.
+
+export type RegistryEntryStatus = "ok" | "error" | "pending" | string;
+
+export interface RegistryEntry {
+  id: string;
+  owner?: string;
+  repo?: string;
+  format: string;
+  graph_url: string;
+  description?: string;
+  status?: RegistryEntryStatus;
+  tags?: string[];
+  last_sha?: string;
+  last_synced?: string;
+  source_sha?: string;
+  head_sha?: string;
+  commits_behind?: number;
+  // Forward-compat: any additional fields we have not modelled yet.
+  [key: string]: unknown;
+}
+
+export interface Registry {
+  schema_version: number;
+  generated_at: string;
+  entries: RegistryEntry[];
+  [key: string]: unknown;
+}
+
+// Subset of an entry returned by `list_repos`. Mirrors the spec.
+export interface RepoSummary {
+  id: string;
+  format: string;
+  description?: string;
+  status?: RegistryEntryStatus;
+  tags?: string[];
+  last_synced?: string;
+  graph_url: string;
+}
+
+export interface ListReposParams {
+  format?: string;
+  tag?: string;
+  status?: string;
+}
+
+export interface GetGraphParams {
+  id: string;
+}
+
+export interface SearchConceptsParams {
+  query: string;
+  id?: string;
+}
+
+export interface SearchHit {
+  node_id?: string;
+  label?: string;
+  name?: string;
+  matched_field: "id" | "label" | "name";
+  matched_value: string;
+}
+
+export interface FindGraphForRepoParams {
+  id?: string;
+  github_url?: string;
+}
+
+// Shape of `stats.json` produced by scripts/aggregate.mjs. Only the fields the
+// MCP server consumes are typed; other fields are kept as `unknown`.
+export interface StatsConcept {
+  term: string;
+  entries: number;
+  samples: string[];
+}
+
+export interface StatsJson {
+  schema_version: number;
+  generated_at: string;
+  totals?: { entries: number; nodes: number; edges: number };
+  kinds?: unknown[];
+  languages?: unknown[];
+  concepts: StatsConcept[];
+  [key: string]: unknown;
+}
+
+// `fetch` and `Response` are global in Node 20+, but we keep a narrow alias
+// so that callers can inject a fake during tests without pulling in DOM lib.
+export type FetchImpl = (
+  input: string | URL,
+  init?: { signal?: AbortSignal },
+) => Promise<{
+  ok: boolean;
+  status: number;
+  statusText: string;
+  json: () => Promise<unknown>;
+  text: () => Promise<string>;
+}>;

package/tests/registry.test.ts

@@ -0,0 +1,171 @@
+import { describe, it, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  clearCache,
+  filterEntries,
+  loadRegistry,
+} from "../src/registry.ts";
+import type { FetchImpl, Registry, RegistryEntry } from "../src/types.ts";
+
+const SOURCE = "https://example.invalid/registry.json";
+
+function makeRegistry(extras: Partial<Registry> = {}): Registry {
+  const entries: RegistryEntry[] = [
+    {
+      id: "alice/python-graph",
+      format: "understand-anything@1",
+      graph_url: "https://example.invalid/alice.json",
+      status: "ok",
+      tags: ["python", "agents"],
+    },
+    {
+      id: "bob/ts-graph",
+      format: "understand-anything@1",
+      graph_url: "https://example.invalid/bob.json",
+      status: "error",
+      tags: ["typescript"],
+    },
+    {
+      id: "carol/rust-graph",
+      format: "gitnexus@1",
+      graph_url: "https://example.invalid/carol.json",
+      status: "ok",
+      tags: ["rust", "agents"],
+    },
+  ];
+  return {
+    schema_version: 1,
+    generated_at: "2026-05-07T00:00:00Z",
+    entries,
+    ...extras,
+  };
+}
+
+function makeFakeFetch(
+  registry: Registry,
+  counter: { calls: number },
+  overrides: Partial<{ ok: boolean; status: number }> = {},
+): FetchImpl {
+  return async () => {
+    counter.calls += 1;
+    return {
+      ok: overrides.ok ?? true,
+      status: overrides.status ?? 200,
+      statusText: "OK",
+      json: async () => registry,
+      text: async () => JSON.stringify(registry),
+    };
+  };
+}
+
+describe("loadRegistry caching", () => {
+  beforeEach(() => clearCache());
+
+  it("fetches once and serves a cache hit on the second call", async () => {
+    const counter = { calls: 0 };
+    const registry = makeRegistry();
+    const fetchImpl = makeFakeFetch(registry, counter);
+    const now = () => 1_000_000;
+
+    const first = await loadRegistry({
+      source: SOURCE,
+      fetchImpl,
+      ttlMs: 60_000,
+      now,
+    });
+    const second = await loadRegistry({
+      source: SOURCE,
+      fetchImpl,
+      ttlMs: 60_000,
+      now,
+    });
+
+    assert.equal(counter.calls, 1, "second call should be served from cache");
+    assert.equal(first, second, "both loads should return the same object");
+  });
+
+  it("refetches after the cache TTL expires", async () => {
+    const counter = { calls: 0 };
+    const registry = makeRegistry();
+    const fetchImpl = makeFakeFetch(registry, counter);
+
+    let nowValue = 1_000_000;
+    const now = () => nowValue;
+
+    await loadRegistry({ source: SOURCE, fetchImpl, ttlMs: 60_000, now });
+    nowValue = 1_000_000 + 61_000; // > TTL
+    await loadRegistry({ source: SOURCE, fetchImpl, ttlMs: 60_000, now });
+
+    assert.equal(counter.calls, 2, "expired cache should trigger a refetch");
+  });
+
+  it("throws when the upstream registry returns non-ok", async () => {
+    const counter = { calls: 0 };
+    const registry = makeRegistry();
+    const fetchImpl = makeFakeFetch(registry, counter, {
+      ok: false,
+      status: 503,
+    });
+
+    await assert.rejects(
+      () =>
+        loadRegistry({
+          source: SOURCE,
+          fetchImpl,
+          ttlMs: 60_000,
+          now: () => 1,
+        }),
+      /Failed to fetch registry/,
+    );
+  });
+});
+
+describe("filterEntries", () => {
+  const registry = makeRegistry();
+
+  it("filters by exact format match", () => {
+    const out = filterEntries(
+      registry.entries,
+      (e) => e.format === "understand-anything@1",
+    );
+    assert.equal(out.length, 2);
+    assert.deepEqual(
+      out.map((e) => e.id),
+      ["alice/python-graph", "bob/ts-graph"],
+    );
+  });
+
+  it("filters by status", () => {
+    const out = filterEntries(registry.entries, (e) => e.status === "ok");
+    assert.equal(out.length, 2);
+    assert.deepEqual(
+      out.map((e) => e.id),
+      ["alice/python-graph", "carol/rust-graph"],
+    );
+  });
+
+  it("filters by tag membership", () => {
+    const out = filterEntries(registry.entries, (e) =>
+      (e.tags ?? []).includes("agents"),
+    );
+    assert.equal(out.length, 2);
+    assert.deepEqual(
+      out.map((e) => e.id),
+      ["alice/python-graph", "carol/rust-graph"],
+    );
+  });
+
+  it("filters by combined predicates (status=ok AND tag=agents)", () => {
+    const out = filterEntries(
+      registry.entries,
+      (e) => e.status === "ok" && (e.tags ?? []).includes("agents"),
+    );
+    assert.equal(out.length, 2);
+  });
+
+  it("returns an empty list when nothing matches", () => {
+    const out = filterEntries(registry.entries, (e) => e.format === "nope");
+    assert.equal(out.length, 0);
+  });
+});