@runcontext/mcp 0.1.1 → 0.2.1

package/dist/index.mjs

@@ -1,423 +1,455 @@
 // src/server.ts
-import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
+import { McpServer as McpServer3 } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { compile, emitManifest, loadConfig } from "@runcontext/core";
 
 // src/resources/manifest.ts
-function readManifest(manifest) {
-  return {
-    contents: [
-      {
-        uri: "context://manifest",
-        mimeType: "application/json",
-        text: JSON.stringify(manifest, null, 2)
-      }
-    ]
-  };
-}
-
-// src/resources/concept.ts
-function readConcept(manifest, id) {
-  const concept = manifest.concepts.find((c) => c.id === id);
-  if (!concept) {
-    return {
+function registerManifestResource(server, manifest) {
+  server.resource(
+    "manifest",
+    "context://manifest",
+    { description: "Full ContextKit manifest JSON (models, governance, rules, lineage, terms, owners, tiers)" },
+    async (uri) => ({
       contents: [
         {
-          uri: `context://concept/${id}`,
+          uri: uri.href,
           mimeType: "application/json",
-          text: JSON.stringify({ error: `Concept not found: ${id}` })
+          text: JSON.stringify(manifest, null, 2)
         }
       ]
-    };
-  }
-  return {
-    contents: [
-      {
-        uri: `context://concept/${id}`,
-        mimeType: "application/json",
-        text: JSON.stringify(concept, null, 2)
-      }
-    ]
-  };
-}
-function listConcepts(manifest) {
-  return {
-    resources: manifest.concepts.map((c) => ({
-      uri: `context://concept/${c.id}`,
-      name: c.id,
-      description: c.definition,
-      mimeType: "application/json"
-    }))
-  };
+    })
+  );
 }
 
-// src/resources/product.ts
-function readProduct(manifest, id) {
-  const product = manifest.products.find((p) => p.id === id);
-  if (!product) {
-    return {
-      contents: [
-        {
-          uri: `context://product/${id}`,
-          mimeType: "application/json",
-          text: JSON.stringify({ error: `Product not found: ${id}` })
-        }
-      ]
-    };
-  }
+// src/resources/model.ts
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+function buildModelView(name, manifest) {
+  const model = manifest.models[name];
+  if (!model) return null;
   return {
-    contents: [
-      {
-        uri: `context://product/${id}`,
-        mimeType: "application/json",
-        text: JSON.stringify(product, null, 2)
-      }
-    ]
+    model,
+    governance: manifest.governance[name] ?? null,
+    rules: manifest.rules[name] ?? null,
+    lineage: manifest.lineage[name] ?? null,
+    tier: manifest.tiers[name] ?? null
   };
 }
-function listProducts(manifest) {
-  return {
-    resources: manifest.products.map((p) => ({
-      uri: `context://product/${p.id}`,
-      name: p.id,
-      description: p.description,
-      mimeType: "application/json"
-    }))
-  };
+function registerModelResource(server, manifest) {
+  server.resource(
+    "model",
+    new ResourceTemplate("context://model/{name}", {
+      list: async () => ({
+        resources: Object.keys(manifest.models).map((name) => ({
+          uri: `context://model/${name}`,
+          name,
+          description: manifest.models[name]?.description ?? `Model: ${name}`
+        }))
+      })
+    }),
+    { description: "OSI semantic model merged with governance, rules, lineage, and tier" },
+    async (uri, { name }) => {
+      const modelName = String(name);
+      const view = buildModelView(modelName, manifest);
+      if (!view) {
+        throw new Error(`Model '${modelName}' not found`);
+      }
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(view, null, 2)
+          }
+        ]
+      };
+    }
+  );
 }
 
-// src/resources/policy.ts
-function readPolicy(manifest, id) {
-  const policy = manifest.policies.find((p) => p.id === id);
-  if (!policy) {
-    return {
+// src/resources/glossary.ts
+function registerGlossaryResource(server, manifest) {
+  server.resource(
+    "glossary",
+    "context://glossary",
+    { description: "All ContextKit glossary terms with definitions, synonyms, and mappings" },
+    async (uri) => ({
       contents: [
         {
-          uri: `context://policy/${id}`,
+          uri: uri.href,
           mimeType: "application/json",
-          text: JSON.stringify({ error: `Policy not found: ${id}` })
+          text: JSON.stringify(manifest.terms, null, 2)
         }
       ]
-    };
-  }
-  return {
-    contents: [
-      {
-        uri: `context://policy/${id}`,
-        mimeType: "application/json",
-        text: JSON.stringify(policy, null, 2)
-      }
-    ]
-  };
-}
-function listPolicies(manifest) {
-  return {
-    resources: manifest.policies.map((p) => ({
-      uri: `context://policy/${p.id}`,
-      name: p.id,
-      description: p.description,
-      mimeType: "application/json"
-    }))
-  };
+    })
+  );
 }
 
-// src/resources/glossary.ts
-function readGlossary(manifest) {
-  const glossary = manifest.terms.map((t) => ({
-    id: t.id,
-    definition: t.definition,
-    synonyms: t.synonyms ?? [],
-    mapsTo: t.mapsTo ?? []
-  }));
-  return {
-    contents: [
-      {
-        uri: "context://glossary",
-        mimeType: "application/json",
-        text: JSON.stringify(glossary, null, 2)
+// src/resources/tier.ts
+import { ResourceTemplate as ResourceTemplate2 } from "@modelcontextprotocol/sdk/server/mcp.js";
+function registerTierResource(server, manifest) {
+  server.resource(
+    "tier",
+    new ResourceTemplate2("context://tier/{name}", {
+      list: async () => ({
+        resources: Object.keys(manifest.tiers).map((name) => ({
+          uri: `context://tier/${name}`,
+          name,
+          description: `Tier scorecard for model: ${name} (${manifest.tiers[name]?.tier ?? "unknown"})`
+        }))
+      })
+    }),
+    { description: "Tier scorecard for a model (bronze/silver/gold checks and results)" },
+    async (uri, { name }) => {
+      const modelName = String(name);
+      const tier = manifest.tiers[modelName];
+      if (!tier) {
+        throw new Error(`Tier data for model '${modelName}' not found`);
       }
-    ]
-  };
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(tier, null, 2)
+          }
+        ]
+      };
+    }
+  );
 }
 
 // src/tools/search.ts
-function searchContext(manifest, query) {
+import { z } from "zod";
+function searchManifest(manifest, query) {
+  const results = [];
   const q = query.toLowerCase();
-  const items = [
-    ...manifest.concepts.map((c) => ({
-      kind: "concept",
-      id: c.id,
-      definition: c.definition,
-      tags: c.tags
-    })),
-    ...manifest.products.map((p) => ({
-      kind: "product",
-      id: p.id,
-      description: p.description,
-      tags: p.tags
-    })),
-    ...manifest.policies.map((p) => ({
-      kind: "policy",
-      id: p.id,
-      description: p.description,
-      tags: p.tags
-    })),
-    ...manifest.entities.map((e) => ({
-      kind: "entity",
-      id: e.id,
-      definition: e.definition,
-      tags: e.tags
-    })),
-    ...manifest.terms.map((t) => ({
-      kind: "term",
-      id: t.id,
-      definition: t.definition,
-      tags: t.tags
-    }))
-  ];
-  const matches = items.filter((item) => {
-    if (item.id.toLowerCase().includes(q)) return true;
-    if (item.definition && item.definition.toLowerCase().includes(q)) return true;
-    if (item.description && item.description.toLowerCase().includes(q)) return true;
-    if (item.tags && item.tags.some((tag) => tag.toLowerCase().includes(q))) return true;
-    return false;
-  });
-  return {
-    content: [
-      {
-        type: "text",
-        text: JSON.stringify({ query, resultCount: matches.length, results: matches }, null, 2)
+  for (const [name, model] of Object.entries(manifest.models)) {
+    if (name.toLowerCase().includes(q) || model.description?.toLowerCase().includes(q)) {
+      results.push({
+        type: "model",
+        name,
+        description: model.description
+      });
+    }
+    for (const ds of model.datasets ?? []) {
+      if (ds.name.toLowerCase().includes(q) || ds.description?.toLowerCase().includes(q)) {
+        results.push({
+          type: "dataset",
+          name: ds.name,
+          description: ds.description,
+          model: name
+        });
       }
-    ]
-  };
-}
-
-// src/tools/explain.ts
-function explainNode(manifest, id) {
-  const index = manifest.indexes.byId[id];
-  if (!index) {
-    return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify({ error: `Node not found: ${id}` }, null, 2)
+      if (ds.fields) {
+        for (const field of ds.fields) {
+          if (field.name.toLowerCase().includes(q) || field.description?.toLowerCase().includes(q) || field.label?.toLowerCase().includes(q)) {
+            results.push({
+              type: "field",
+              name: field.name,
+              description: field.description,
+              model: name,
+              dataset: ds.name
+            });
+          }
         }
-      ]
-    };
-  }
-  let node;
-  switch (index.kind) {
-    case "concept":
-      node = manifest.concepts[index.index];
-      break;
-    case "product":
-      node = manifest.products[index.index];
-      break;
-    case "policy":
-      node = manifest.policies[index.index];
-      break;
-    case "entity":
-      node = manifest.entities[index.index];
-      break;
-    case "term":
-      node = manifest.terms[index.index];
-      break;
-    case "owner":
-      node = manifest.owners[index.index];
-      break;
-  }
-  if (!node) {
-    return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify({ error: `Node data not found for: ${id}` }, null, 2)
-        }
-      ]
-    };
-  }
-  const dependencies = [];
-  const dependsOn = node.dependsOn;
-  if (dependsOn) {
-    for (const depId of dependsOn) {
-      const depIndex = manifest.indexes.byId[depId];
-      if (depIndex) {
-        dependencies.push({ id: depId, kind: depIndex.kind });
       }
     }
   }
-  const dependents = [];
-  for (const concept of manifest.concepts) {
-    if (concept.dependsOn?.includes(id)) {
-      dependents.push({ id: concept.id, kind: "concept" });
+  for (const [id, term] of Object.entries(manifest.terms)) {
+    if (id.toLowerCase().includes(q) || term.definition.toLowerCase().includes(q) || term.synonyms?.some((s) => s.toLowerCase().includes(q))) {
+      results.push({
+        type: "term",
+        name: id,
+        description: term.definition
+      });
     }
   }
-  const applicablePolicies = [];
-  const nodeTags = node.tags ?? [];
-  for (const policy of manifest.policies) {
-    const applies = policy.rules.some((rule) => {
-      if (rule.when.conceptIds?.includes(id)) return true;
-      if (rule.when.tagsAny?.some((tag) => nodeTags.includes(tag))) return true;
-      return false;
-    });
-    if (applies) {
-      applicablePolicies.push({ id: policy.id, description: policy.description });
+  for (const [id, owner] of Object.entries(manifest.owners)) {
+    if (id.toLowerCase().includes(q) || owner.display_name.toLowerCase().includes(q) || owner.description?.toLowerCase().includes(q)) {
+      results.push({
+        type: "owner",
+        name: id,
+        description: owner.display_name
+      });
     }
   }
-  let ownerInfo;
-  const ownerId = node.owner;
-  if (ownerId) {
-    ownerInfo = manifest.owners.find((o) => o.id === ownerId);
+  return results;
+}
+function registerSearchTool(server, manifest) {
+  server.tool(
+    "context_search",
+    "Search across all ContextKit nodes (models, datasets, fields, terms, owners) by keyword",
+    { query: z.string().describe("Keyword to search for") },
+    async ({ query }) => {
+      const results = searchManifest(manifest, query);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(results, null, 2)
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/tools/explain.ts
+import { z as z2 } from "zod";
+function explainModel(name, manifest) {
+  const model = manifest.models[name];
+  if (!model) return null;
+  const governance = manifest.governance[name] ?? null;
+  const rules = manifest.rules[name] ?? null;
+  const lineage = manifest.lineage[name] ?? null;
+  const tier = manifest.tiers[name] ?? null;
+  const ownerKey = governance?.owner;
+  const owner = ownerKey ? manifest.owners[ownerKey] ?? null : null;
+  const modelTags = governance?.tags ?? [];
+  const relatedTerms = [];
+  for (const [, term] of Object.entries(manifest.terms)) {
+    const termTags = term.tags ?? [];
+    const hasOverlap = modelTags.some((t) => termTags.includes(t));
+    const mapsToModel = term.maps_to?.some((m) => m === name);
+    if (hasOverlap || mapsToModel) {
+      relatedTerms.push(term);
+    }
   }
-  const result = {
-    kind: index.kind,
-    node,
-    dependencies,
-    dependents,
-    applicablePolicies,
-    owner: ownerInfo ?? null
-  };
   return {
-    content: [
-      {
-        type: "text",
-        text: JSON.stringify(result, null, 2)
-      }
-    ]
+    model,
+    governance,
+    rules,
+    lineage,
+    tier,
+    owner,
+    relatedTerms
   };
 }
+function registerExplainTool(server, manifest) {
+  server.tool(
+    "context_explain",
+    "Deep lookup of a model with all related governance, rules, lineage, tier, owner, and glossary terms",
+    { model: z2.string().describe("Name of the model to explain") },
+    async ({ model }) => {
+      const result = explainModel(model, manifest);
+      if (!result) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: `Model '${model}' not found` })
+            }
+          ]
+        };
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result, null, 2)
+          }
+        ]
+      };
+    }
+  );
+}
 
 // src/tools/validate.ts
-async function validateContext(rootDir) {
-  try {
-    const { compile, LintEngine, ALL_RULES } = await import("@runcontext/core");
-    const contextDir = rootDir ?? process.cwd();
-    const compileResult = await compile({
-      contextDir,
-      config: {}
-    });
-    const engine = new LintEngine();
-    for (const rule of ALL_RULES) {
-      engine.register(rule);
-    }
-    const lintDiagnostics = engine.run(compileResult.graph);
-    const allDiagnostics = [...compileResult.diagnostics, ...lintDiagnostics];
-    const summary = {
-      contextDir,
-      compileDiagnostics: compileResult.diagnostics.length,
-      lintDiagnostics: lintDiagnostics.length,
-      totalDiagnostics: allDiagnostics.length,
-      errors: allDiagnostics.filter((d) => d.severity === "error").length,
-      warnings: allDiagnostics.filter((d) => d.severity === "warning").length,
-      diagnostics: allDiagnostics
-    };
-    return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify(summary, null, 2)
-        }
-      ]
-    };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify({ error: `Validation failed: ${message}` }, null, 2)
-        }
-      ],
-      isError: true
-    };
+import { LintEngine, ALL_RULES } from "@runcontext/core";
+function validateGraph(graph) {
+  const engine = new LintEngine();
+  for (const rule of ALL_RULES) {
+    engine.register(rule);
   }
+  const diagnostics = engine.run(graph);
+  const errors = diagnostics.filter((d) => d.severity === "error").length;
+  const warnings = diagnostics.filter((d) => d.severity === "warning").length;
+  return {
+    totalDiagnostics: diagnostics.length,
+    errors,
+    warnings,
+    diagnostics
+  };
 }
-
-// src/server.ts
-function createContextMcpServer(manifest) {
-  const server = new McpServer(
-    {
-      name: "contextkit",
-      version: "0.1.0"
-    },
-    {
-      capabilities: {
-        resources: {},
-        tools: {}
-      }
+function registerValidateTool(server, graph) {
+  server.tool(
+    "context_validate",
+    "Run ContextKit linter against the context graph and return diagnostics",
+    {},
+    async () => {
+      const result = validateGraph(graph);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result, null, 2)
+          }
+        ]
+      };
     }
   );
-  server.resource(
-    "manifest",
-    "context://manifest",
-    { description: "The full ContextKit manifest", mimeType: "application/json" },
-    () => readManifest(manifest)
-  );
-  server.resource(
-    "glossary",
-    "context://glossary",
-    { description: "Glossary of all terms", mimeType: "application/json" },
-    () => readGlossary(manifest)
-  );
-  server.resource(
-    "concept",
-    new ResourceTemplate("context://concept/{id}", {
-      list: () => listConcepts(manifest)
-    }),
-    { description: "A single concept by ID", mimeType: "application/json" },
-    (uri, variables) => readConcept(manifest, String(variables.id))
-  );
-  server.resource(
-    "product",
-    new ResourceTemplate("context://product/{id}", {
-      list: () => listProducts(manifest)
-    }),
-    { description: "A single product by ID", mimeType: "application/json" },
-    (uri, variables) => readProduct(manifest, String(variables.id))
-  );
-  server.resource(
-    "policy",
-    new ResourceTemplate("context://policy/{id}", {
-      list: () => listPolicies(manifest)
-    }),
-    { description: "A single policy by ID", mimeType: "application/json" },
-    (uri, variables) => readPolicy(manifest, String(variables.id))
-  );
+}
+
+// src/tools/tier.ts
+import { z as z3 } from "zod";
+import { computeTier } from "@runcontext/core";
+function computeModelTier(modelName, graph) {
+  if (!graph.models.has(modelName)) return null;
+  return computeTier(modelName, graph);
+}
+function registerTierTool(server, graph) {
   server.tool(
-    "context_search",
-    "Search across all concepts, products, policies, entities, and terms",
-    { query: z.string().describe("The search query (case-insensitive substring match)") },
-    ({ query }) => searchContext(manifest, query)
+    "context_tier",
+    "Compute the metadata tier (none/bronze/silver/gold) for a model with detailed check results",
+    { model: z3.string().describe("Name of the model to tier") },
+    async ({ model }) => {
+      const result = computeModelTier(model, graph);
+      if (!result) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: `Model '${model}' not found` })
+            }
+          ]
+        };
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result, null, 2)
+          }
+        ]
+      };
+    }
   );
+}
+
+// src/tools/golden-query.ts
+import { z as z4 } from "zod";
+function findGoldenQueries(manifest, question) {
+  const stopWords = /* @__PURE__ */ new Set(["a", "an", "the", "is", "in", "on", "at", "to", "of", "for", "and", "or", "not"]);
+  const qWords = question.toLowerCase().split(/\s+/).filter((w) => w.length > 0 && !stopWords.has(w));
+  const matches = [];
+  for (const [modelName, rules] of Object.entries(manifest.rules)) {
+    if (!rules.golden_queries) continue;
+    for (const gq of rules.golden_queries) {
+      const gqWords = gq.question.toLowerCase().split(/\s+/);
+      const overlap = qWords.filter((w) => gqWords.some((gw) => gw.includes(w))).length;
+      if (overlap > 0) {
+        matches.push({
+          model: modelName,
+          query: gq,
+          score: overlap / Math.max(qWords.length, 1)
+        });
+      }
+    }
+  }
+  matches.sort((a, b) => b.score - a.score);
+  return matches;
+}
+function registerGoldenQueryTool(server, manifest) {
   server.tool(
-    "context_explain",
-    "Get comprehensive info about a node: the node itself, dependencies, dependents, applicable policies, and owner",
-    { id: z.string().describe("The ID of the node to explain") },
-    ({ id }) => explainNode(manifest, id)
+    "context_golden_query",
+    "Find golden SQL queries that match a natural-language question",
+    { question: z4.string().describe("Natural-language question to match against golden queries") },
+    async ({ question }) => {
+      const results = findGoldenQueries(manifest, question);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(results, null, 2)
+          }
+        ]
+      };
+    }
   );
+}
+
+// src/tools/guardrails.ts
+import { z as z5 } from "zod";
+function findGuardrails(manifest, tables) {
+  const matches = [];
+  const tableSet = new Set(tables.map((t) => t.toLowerCase()));
+  for (const [modelName, rules] of Object.entries(manifest.rules)) {
+    if (!rules.guardrail_filters) continue;
+    for (const gf of rules.guardrail_filters) {
+      const applies = !gf.tables || gf.tables.length === 0 || gf.tables.some((t) => tableSet.has(t.toLowerCase()));
+      if (applies) {
+        matches.push({
+          model: modelName,
+          filter: gf
+        });
+      }
+    }
+  }
+  return matches;
+}
+function registerGuardrailsTool(server, manifest) {
   server.tool(
-    "context_validate",
-    "Run compile and lint validation on the context directory and return diagnostics",
-    { rootDir: z.string().optional().describe("Root directory to validate (defaults to cwd)") },
-    async ({ rootDir }) => validateContext(rootDir)
+    "context_guardrails",
+    "Return guardrail filters that apply to the specified tables",
+    {
+      tables: z5.array(z5.string()).describe("List of table names to check guardrails for")
+    },
+    async ({ tables }) => {
+      const results = findGuardrails(manifest, tables);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(results, null, 2)
+          }
+        ]
+      };
+    }
   );
-  return server;
 }
 
-// src/index.ts
-var MCP_VERSION = "0.1.0";
+// src/server.ts
+function createServer(manifest, graph) {
+  const server = new McpServer3({
+    name: "contextkit",
+    version: "0.2.0"
+  });
+  registerManifestResource(server, manifest);
+  registerModelResource(server, manifest);
+  registerGlossaryResource(server, manifest);
+  registerTierResource(server, manifest);
+  registerSearchTool(server, manifest);
+  registerExplainTool(server, manifest);
+  registerValidateTool(server, graph);
+  registerTierTool(server, graph);
+  registerGoldenQueryTool(server, manifest);
+  registerGuardrailsTool(server, manifest);
+  return server;
+}
+async function startServer(options) {
+  const rootDir = options?.rootDir ?? process.cwd();
+  const config = loadConfig(rootDir);
+  const contextDir = options?.contextDir ?? config.context_dir;
+  const { graph } = await compile({ contextDir, config });
+  const manifest = emitManifest(graph, config);
+  const server = createServer(manifest, graph);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  return server;
+}
 export {
-  MCP_VERSION,
-  createContextMcpServer,
-  explainNode,
-  listConcepts,
-  listPolicies,
-  listProducts,
-  readConcept,
-  readGlossary,
-  readManifest,
-  readPolicy,
-  readProduct,
-  searchContext,
-  validateContext
+  buildModelView,
+  computeModelTier,
+  createServer,
+  explainModel,
+  findGoldenQueries,
+  findGuardrails,
+  registerGlossaryResource,
+  registerManifestResource,
+  registerModelResource,
+  registerTierResource,
+  searchManifest,
+  startServer,
+  validateGraph
 };
 //# sourceMappingURL=index.mjs.map