@svashevchenko/ez-know 0.1.0 → 0.2.0

package/dist/server.js

@@ -2387,6 +2387,442 @@ function buildKnowledgeGraphQLText(result) {
   });
 }
 
+// packages/core/src/knowledge/schema-discovery.ts
+import {
+  isAbstractType,
+  isCompositeType,
+  isListType,
+  isNonNullType,
+  isObjectType,
+  isScalarType,
+  isUnionType
+} from "graphql";
+var KNOWLEDGE_SCHEMA_RESOURCE_URI = "ez-know://schema";
+var KNOWLEDGE_SCHEMA_LOOKUP_URI = "ez-know://lookup/{target}";
+function unwrapType(type) {
+  if (isNonNullType(type) || isListType(type)) {
+    return unwrapType(type.ofType);
+  }
+  if (isObjectType(type) || isScalarType(type) || isUnionType(type) || isAbstractType(type)) {
+    return { name: type.name, composite: type };
+  }
+  return { name: "Unknown", composite: type };
+}
+function describeType(type) {
+  if (isNonNullType(type)) {
+    return `${describeType(type.ofType)}!`;
+  }
+  if (isListType(type)) {
+    return `[${describeType(type.ofType)}]`;
+  }
+  if (isObjectType(type) || isScalarType(type) || isUnionType(type)) {
+    return type.name;
+  }
+  if (isAbstractType(type)) {
+    return type.name;
+  }
+  return "Unknown";
+}
+function formatDefaultValue(value) {
+  if (value === void 0 || value === null) {
+    return null;
+  }
+  return JSON.stringify(value) ?? String(value);
+}
+function summarizeField(field) {
+  const traversedType = unwrapType(field.type).composite;
+  const traversesTo = isCompositeType(traversedType) && !isScalarType(traversedType) ? traversedType.name : null;
+  return {
+    name: field.name,
+    type: describeType(field.type),
+    description: field.description ?? null,
+    arguments: field.args?.map((argument) => ({
+      name: argument.name,
+      type: describeType(argument.type),
+      description: argument.description ?? null,
+      defaultValue: formatDefaultValue(argument.defaultValue)
+    })) ?? [],
+    traversesTo
+  };
+}
+function summarizeObjectType(type) {
+  const fields = Object.values(type.getFields()).map(summarizeField);
+  return {
+    name: type.name,
+    description: type.description ?? null,
+    fields,
+    traversalFields: fields.filter((field) => field.traversesTo !== null).map((field) => field.name)
+  };
+}
+function getObjectTypes(schema) {
+  return Object.values(schema.getTypeMap()).filter((type) => isObjectType(type)).filter((type) => !type.name.startsWith("__")).filter((type) => type.name !== schema.getQueryType()?.name);
+}
+function buildKnowledgeSchemaDiscoveryDocument(schema) {
+  const queryType2 = schema.getQueryType();
+  if (!queryType2) {
+    throw new Error("Knowledge GraphQL schema has no root query type.");
+  }
+  return {
+    resource: {
+      uri: KNOWLEDGE_SCHEMA_RESOURCE_URI,
+      title: "Knowledge GraphQL Schema",
+      description: "Canonical discovery view of the runtime knowledge GraphQL schema."
+    },
+    source: {
+      kind: "runtime-schema",
+      queryType: queryType2.name
+    },
+    rootQuery: summarizeObjectType(queryType2),
+    objectTypes: getObjectTypes(schema).map(summarizeObjectType)
+  };
+}
+function getLookupMetadata(schema, target) {
+  const queryType2 = schema.getQueryType();
+  if (!queryType2) {
+    throw new Error("Knowledge GraphQL schema has no root query type.");
+  }
+  if (target === queryType2.name) {
+    return {
+      resource: {
+        uri: `ez-know://lookup/${target}`,
+        title: `Knowledge schema lookup: ${target}`,
+        description: "Focused lookup of the root query fields and their arguments."
+      },
+      source: {
+        kind: "runtime-schema",
+        queryType: queryType2.name
+      },
+      lookup: {
+        target: queryType2.name,
+        kind: "root-query"
+      },
+      rootQuery: summarizeObjectType(queryType2)
+    };
+  }
+  const rootField = queryType2.getFields()[target];
+  if (rootField) {
+    return {
+      resource: {
+        uri: `ez-know://lookup/${target}`,
+        title: `Knowledge schema lookup: ${target}`,
+        description: "Focused lookup of a single root query field and its arguments."
+      },
+      source: {
+        kind: "runtime-schema",
+        queryType: queryType2.name
+      },
+      lookup: {
+        target,
+        kind: "root-field"
+      },
+      field: summarizeField(rootField),
+      parentType: queryType2.name
+    };
+  }
+  const objectType = schema.getType(target);
+  if (objectType && isObjectType(objectType)) {
+    const typeSummary = summarizeObjectType(objectType);
+    const rootFields = Object.values(queryType2.getFields()).filter((field) => unwrapType(field.type).name === target).map((field) => field.name);
+    return {
+      resource: {
+        uri: `ez-know://lookup/${target}`,
+        title: `Knowledge schema lookup: ${target}`,
+        description: "Focused lookup of a single GraphQL type and its nested traversal fields."
+      },
+      source: {
+        kind: "runtime-schema",
+        queryType: queryType2.name
+      },
+      lookup: {
+        target,
+        kind: "object-type"
+      },
+      type: typeSummary,
+      rootFields
+    };
+  }
+  throw new Error(
+    `Unknown schema lookup target "${target}". Use a root field name, a type name, or "Query".`
+  );
+}
+function buildKnowledgeSchemaLookupDocument(schema, target) {
+  return getLookupMetadata(schema, target);
+}
+function listKnowledgeSchemaTargets(schema) {
+  const queryType2 = schema.getQueryType();
+  if (!queryType2) {
+    throw new Error("Knowledge GraphQL schema has no root query type.");
+  }
+  const objectTypeNames = getObjectTypes(schema).map((type) => type.name);
+  const rootFieldNames = Object.keys(queryType2.getFields());
+  const targetNames = ["Query", ...rootFieldNames, ...objectTypeNames];
+  return Array.from(new Set(targetNames)).sort(
+    (left, right) => left.localeCompare(right)
+  );
+}
+
+// packages/core/src/knowledge/resource-catalog.ts
+var KnowledgeResourceNotFoundError = class extends Error {
+  constructor(uri, message = `Unknown ez-know resource URI "${uri}".`) {
+    super(message);
+    this.uri = uri;
+    this.name = "KnowledgeResourceNotFoundError";
+  }
+  uri;
+  code = "RESOURCE_NOT_FOUND";
+};
+var KnowledgeResourceUriError = class extends Error {
+  constructor(uri, message) {
+    super(message);
+    this.uri = uri;
+    this.name = "KnowledgeResourceUriError";
+  }
+  uri;
+  code = "INVALID_RESOURCE_URI";
+};
+function createJsonResourceContent(uri, text) {
+  return {
+    uri,
+    mimeType: "application/json",
+    text
+  };
+}
+function createMarkdownResourceContent(uri, text) {
+  return {
+    uri,
+    mimeType: "text/markdown",
+    text
+  };
+}
+function createKnowledgeSchemaResourceDefinition() {
+  return {
+    uri: KNOWLEDGE_SCHEMA_RESOURCE_URI,
+    name: "knowledge-schema",
+    title: "Knowledge GraphQL Schema",
+    description: "Canonical runtime GraphQL schema discovery payload for the knowledge layer.",
+    mimeType: "application/json",
+    read: () => ({
+      resource: {
+        uri: KNOWLEDGE_SCHEMA_RESOURCE_URI,
+        title: "Knowledge GraphQL Schema",
+        description: "Canonical runtime GraphQL schema discovery payload for the knowledge layer.",
+        mimeType: "application/json"
+      },
+      content: createJsonResourceContent(
+        KNOWLEDGE_SCHEMA_RESOURCE_URI,
+        createKnowledgeSchemaDiscoveryText()
+      )
+    })
+  };
+}
+function createKnowledgeExtractionTypesResourceDefinition() {
+  return {
+    uri: KNOWLEDGE_EXTRACTION_TYPES_RESOURCE_URI,
+    name: "knowledge-extraction-types",
+    title: "Knowledge Extraction Types",
+    description: "Canonical registry of knowledge types supported by the extraction workflow.",
+    mimeType: "application/json",
+    read: () => ({
+      resource: {
+        uri: KNOWLEDGE_EXTRACTION_TYPES_RESOURCE_URI,
+        title: "Knowledge Extraction Types",
+        description: "Canonical registry of knowledge types supported by the extraction workflow.",
+        mimeType: "application/json"
+      },
+      content: createJsonResourceContent(
+        KNOWLEDGE_EXTRACTION_TYPES_RESOURCE_URI,
+        JSON.stringify(buildKnowledgeExtractionTypeIndexDocument(), null, 2)
+      )
+    })
+  };
+}
+function createKnowledgeSchemaLookupTemplateDefinition() {
+  return {
+    uriTemplate: KNOWLEDGE_SCHEMA_LOOKUP_URI,
+    name: "knowledge-schema-lookup",
+    title: "Knowledge Schema Lookup",
+    description: "Focused runtime GraphQL schema lookup for a type name, root field, or Query.",
+    mimeType: "application/json",
+    list: () => listKnowledgeSchemaTargets(knowledgeGraphSchema).map((target) => ({
+      uri: `ez-know://lookup/${target}`,
+      name: target,
+      title: `Knowledge schema lookup: ${target}`,
+      description: target === "Query" ? "Focused lookup of the root query fields." : `Focused lookup of ${target}.`,
+      mimeType: "application/json"
+    })),
+    read: (uri) => {
+      const target = readUriSegment(uri, "ez-know://lookup/");
+      try {
+        return {
+          resource: {
+            uri,
+            title: `Knowledge schema lookup: ${target}`,
+            description: target === "Query" ? "Focused lookup of the root query fields and their arguments." : `Focused lookup of ${target}.`,
+            mimeType: "application/json"
+          },
+          content: createJsonResourceContent(
+            uri,
+            createKnowledgeSchemaLookupText(target)
+          )
+        };
+      } catch (error) {
+        if (error instanceof Error) {
+          throw new KnowledgeResourceUriError(uri, error.message);
+        }
+        throw error;
+      }
+    }
+  };
+}
+function createKnowledgeExtractionSchemaTemplateDefinition() {
+  return {
+    uriTemplate: KNOWLEDGE_EXTRACTION_SCHEMA_RESOURCE_URI,
+    name: "knowledge-extraction-schema",
+    title: "Knowledge Extraction Schema",
+    description: "Runtime JSON-schema discovery for a supported knowledge type.",
+    mimeType: "application/json",
+    list: () => listKnowledgeExtractionResourceTypes().map((definition) => ({
+      uri: `ez-know://extraction/schema/${definition.collection}`,
+      name: definition.collection,
+      title: `${definition.title} Extraction Schema`,
+      description: `Runtime schema discovery for ${definition.title.toLowerCase()}.`,
+      mimeType: "application/json"
+    })),
+    read: (uri) => {
+      const type = readUriSegment(uri, "ez-know://extraction/schema/");
+      try {
+        const document = buildKnowledgeExtractionSchemaDocument(type);
+        return {
+          resource: {
+            uri: `ez-know://extraction/schema/${document.type.collection}`,
+            title: `${document.type.title} Extraction Schema`,
+            description: "Runtime JSON Schema view of the canonical knowledge object model.",
+            mimeType: "application/json"
+          },
+          content: createJsonResourceContent(
+            `ez-know://extraction/schema/${document.type.collection}`,
+            JSON.stringify(document, null, 2)
+          )
+        };
+      } catch (error) {
+        if (error instanceof Error) {
+          throw new KnowledgeResourceUriError(uri, error.message);
+        }
+        throw error;
+      }
+    }
+  };
+}
+function createKnowledgeExtractionGuideTemplateDefinition() {
+  return {
+    uriTemplate: KNOWLEDGE_EXTRACTION_GUIDE_RESOURCE_URI,
+    name: "knowledge-extraction-guide",
+    title: "Knowledge Extraction Guide",
+    description: "Checked-in Markdown guidance for a supported knowledge type.",
+    mimeType: "text/markdown",
+    list: () => listKnowledgeExtractionResourceTypes().map((definition) => ({
+      uri: `ez-know://extraction/guide/${definition.collection}`,
+      name: definition.collection,
+      title: `${definition.title} Extraction Guide`,
+      description: `Checked-in extraction guidance for ${definition.title.toLowerCase()}.`,
+      mimeType: "text/markdown"
+    })),
+    read: async (uri) => {
+      const type = readUriSegment(uri, "ez-know://extraction/guide/");
+      try {
+        const document = await buildKnowledgeExtractionGuideDocument(type);
+        return {
+          resource: {
+            uri: `ez-know://extraction/guide/${document.type.collection}`,
+            title: `${document.type.title} Extraction Guide`,
+            description: "Checked-in Markdown guidance for extracting this knowledge type.",
+            mimeType: "text/markdown"
+          },
+          content: createMarkdownResourceContent(
+            `ez-know://extraction/guide/${document.type.collection}`,
+            document.markdown
+          )
+        };
+      } catch (error) {
+        if (error instanceof Error) {
+          throw new KnowledgeResourceUriError(uri, error.message);
+        }
+        throw error;
+      }
+    }
+  };
+}
+function createKnowledgeSchemaDiscoveryText() {
+  return JSON.stringify(buildKnowledgeSchemaDiscoveryDocument(knowledgeGraphSchema), null, 2);
+}
+function createKnowledgeSchemaLookupText(target) {
+  return JSON.stringify(
+    buildKnowledgeSchemaLookupDocument(knowledgeGraphSchema, target),
+    null,
+    2
+  );
+}
+function readUriSegment(uri, prefix) {
+  if (!uri.startsWith(prefix)) {
+    throw new KnowledgeResourceNotFoundError(uri);
+  }
+  const segment = uri.slice(prefix.length);
+  if (segment.length === 0 || segment.includes("/")) {
+    throw new KnowledgeResourceUriError(
+      uri,
+      `Unsupported ez-know resource URI "${uri}".`
+    );
+  }
+  return segment;
+}
+var KNOWLEDGE_RESOURCE_DEFINITIONS = [
+  createKnowledgeSchemaResourceDefinition(),
+  createKnowledgeExtractionTypesResourceDefinition()
+];
+var KNOWLEDGE_RESOURCE_TEMPLATE_DEFINITIONS = [
+  createKnowledgeSchemaLookupTemplateDefinition(),
+  createKnowledgeExtractionSchemaTemplateDefinition(),
+  createKnowledgeExtractionGuideTemplateDefinition()
+];
+function listKnowledgeResourceEntries() {
+  return KNOWLEDGE_RESOURCE_DEFINITIONS.map(({ read: _read, ...metadata }) => ({
+    ...metadata
+  }));
+}
+function listKnowledgeResourceTemplateEntries() {
+  return KNOWLEDGE_RESOURCE_TEMPLATE_DEFINITIONS.map(({ list: _list, read: _read, ...metadata }) => ({
+    ...metadata
+  }));
+}
+function listKnowledgeResourceTemplateResources(uriTemplate) {
+  const template = KNOWLEDGE_RESOURCE_TEMPLATE_DEFINITIONS.find(
+    (entry) => entry.uriTemplate === uriTemplate
+  );
+  if (!template) {
+    throw new KnowledgeResourceNotFoundError(uriTemplate);
+  }
+  return template.list();
+}
+function getKnowledgeResourceEntry(uri) {
+  return KNOWLEDGE_RESOURCE_DEFINITIONS.find((entry) => entry.uri === uri);
+}
+async function readKnowledgeResourceDocument(uri) {
+  const resource = getKnowledgeResourceEntry(uri);
+  if (resource) {
+    return await resource.read();
+  }
+  if (uri.startsWith("ez-know://lookup/")) {
+    return await createKnowledgeSchemaLookupTemplateDefinition().read(uri);
+  }
+  if (uri.startsWith("ez-know://extraction/schema/")) {
+    return await createKnowledgeExtractionSchemaTemplateDefinition().read(uri);
+  }
+  if (uri.startsWith("ez-know://extraction/guide/")) {
+    return await createKnowledgeExtractionGuideTemplateDefinition().read(uri);
+  }
+  throw new KnowledgeResourceNotFoundError(uri);
+}
+
 // packages/core/src/knowledge/patch/apply.ts
 import { existsSync as existsSync3 } from "node:fs";
 import { mkdir as mkdir2, rm, unlink, writeFile as writeFile2 } from "node:fs/promises";
@@ -2852,214 +3288,8 @@ function buildKnowledgePatchToolText(result) {
   return JSON.stringify(result, null, 2);
 }
 
-// packages/core/src/knowledge/schema-discovery.ts
-import {
-  isAbstractType,
-  isCompositeType,
-  isListType,
-  isNonNullType,
-  isObjectType,
-  isScalarType,
-  isUnionType
-} from "graphql";
-var KNOWLEDGE_SCHEMA_RESOURCE_URI = "knowledge-schema://schema";
-var KNOWLEDGE_SCHEMA_LOOKUP_URI = "knowledge-schema://lookup/{target}";
-function unwrapType(type) {
-  if (isNonNullType(type) || isListType(type)) {
-    return unwrapType(type.ofType);
-  }
-  if (isObjectType(type) || isScalarType(type) || isUnionType(type) || isAbstractType(type)) {
-    return { name: type.name, composite: type };
-  }
-  return { name: "Unknown", composite: type };
-}
-function describeType(type) {
-  if (isNonNullType(type)) {
-    return `${describeType(type.ofType)}!`;
-  }
-  if (isListType(type)) {
-    return `[${describeType(type.ofType)}]`;
-  }
-  if (isObjectType(type) || isScalarType(type) || isUnionType(type)) {
-    return type.name;
-  }
-  if (isAbstractType(type)) {
-    return type.name;
-  }
-  return "Unknown";
-}
-function formatDefaultValue(value) {
-  if (value === void 0 || value === null) {
-    return null;
-  }
-  return JSON.stringify(value) ?? String(value);
-}
-function summarizeField(field) {
-  const traversedType = unwrapType(field.type).composite;
-  const traversesTo = isCompositeType(traversedType) && !isScalarType(traversedType) ? traversedType.name : null;
-  return {
-    name: field.name,
-    type: describeType(field.type),
-    description: field.description ?? null,
-    arguments: field.args?.map((argument) => ({
-      name: argument.name,
-      type: describeType(argument.type),
-      description: argument.description ?? null,
-      defaultValue: formatDefaultValue(argument.defaultValue)
-    })) ?? [],
-    traversesTo
-  };
-}
-function summarizeObjectType(type) {
-  const fields = Object.values(type.getFields()).map(summarizeField);
-  return {
-    name: type.name,
-    description: type.description ?? null,
-    fields,
-    traversalFields: fields.filter((field) => field.traversesTo !== null).map((field) => field.name)
-  };
-}
-function getObjectTypes(schema) {
-  return Object.values(schema.getTypeMap()).filter((type) => isObjectType(type)).filter((type) => !type.name.startsWith("__")).filter((type) => type.name !== schema.getQueryType()?.name);
-}
-function buildKnowledgeSchemaDiscoveryDocument(schema) {
-  const queryType2 = schema.getQueryType();
-  if (!queryType2) {
-    throw new Error("Knowledge GraphQL schema has no root query type.");
-  }
-  return {
-    resource: {
-      uri: KNOWLEDGE_SCHEMA_RESOURCE_URI,
-      title: "Knowledge GraphQL Schema",
-      description: "Canonical discovery view of the runtime knowledge GraphQL schema."
-    },
-    source: {
-      kind: "runtime-schema",
-      queryType: queryType2.name
-    },
-    rootQuery: summarizeObjectType(queryType2),
-    objectTypes: getObjectTypes(schema).map(summarizeObjectType)
-  };
-}
-function getLookupMetadata(schema, target) {
-  const queryType2 = schema.getQueryType();
-  if (!queryType2) {
-    throw new Error("Knowledge GraphQL schema has no root query type.");
-  }
-  if (target === queryType2.name) {
-    return {
-      resource: {
-        uri: `knowledge-schema://lookup/${target}`,
-        title: `Knowledge schema lookup: ${target}`,
-        description: "Focused lookup of the root query fields and their arguments."
-      },
-      source: {
-        kind: "runtime-schema",
-        queryType: queryType2.name
-      },
-      lookup: {
-        target: queryType2.name,
-        kind: "root-query"
-      },
-      rootQuery: summarizeObjectType(queryType2)
-    };
-  }
-  const rootField = queryType2.getFields()[target];
-  if (rootField) {
-    return {
-      resource: {
-        uri: `knowledge-schema://lookup/${target}`,
-        title: `Knowledge schema lookup: ${target}`,
-        description: "Focused lookup of a single root query field and its arguments."
-      },
-      source: {
-        kind: "runtime-schema",
-        queryType: queryType2.name
-      },
-      lookup: {
-        target,
-        kind: "root-field"
-      },
-      field: summarizeField(rootField),
-      parentType: queryType2.name
-    };
-  }
-  const objectType = schema.getType(target);
-  if (objectType && isObjectType(objectType)) {
-    const typeSummary = summarizeObjectType(objectType);
-    const rootFields = Object.values(queryType2.getFields()).filter((field) => unwrapType(field.type).name === target).map((field) => field.name);
-    return {
-      resource: {
-        uri: `knowledge-schema://lookup/${target}`,
-        title: `Knowledge schema lookup: ${target}`,
-        description: "Focused lookup of a single GraphQL type and its nested traversal fields."
-      },
-      source: {
-        kind: "runtime-schema",
-        queryType: queryType2.name
-      },
-      lookup: {
-        target,
-        kind: "object-type"
-      },
-      type: typeSummary,
-      rootFields
-    };
-  }
-  throw new Error(
-    `Unknown schema lookup target "${target}". Use a root field name, a type name, or "Query".`
-  );
-}
-function buildKnowledgeSchemaLookupDocument(schema, target) {
-  return getLookupMetadata(schema, target);
-}
-function createKnowledgeSchemaResourceText(schema) {
-  return JSON.stringify(buildKnowledgeSchemaDiscoveryDocument(schema), null, 2);
-}
-function createKnowledgeSchemaLookupText(schema, target) {
-  return JSON.stringify(
-    buildKnowledgeSchemaLookupDocument(schema, target),
-    null,
-    2
-  );
-}
-function listKnowledgeSchemaTargets(schema) {
-  const queryType2 = schema.getQueryType();
-  if (!queryType2) {
-    throw new Error("Knowledge GraphQL schema has no root query type.");
-  }
-  const objectTypeNames = getObjectTypes(schema).map((type) => type.name);
-  const rootFieldNames = Object.keys(queryType2.getFields());
-  const targetNames = ["Query", ...rootFieldNames, ...objectTypeNames];
-  return Array.from(new Set(targetNames)).sort(
-    (left, right) => left.localeCompare(right)
-  );
-}
-
 // packages/mcp/src/resources/knowledge-extraction.ts
 import { ResourceTemplate } from "@modelcontextprotocol/server";
-function createJsonResourceContent(uri, text) {
-  return {
-    contents: [
-      {
-        uri,
-        mimeType: "application/json",
-        text
-      }
-    ]
-  };
-}
-function createMarkdownResourceContent(uri, text) {
-  return {
-    contents: [
-      {
-        uri,
-        mimeType: "text/markdown",
-        text
-      }
-    ]
-  };
-}
 function listExtractionTypeNames() {
   return listKnowledgeExtractionResourceTypes().flatMap((definition) => [
     definition.collection,
@@ -3067,30 +3297,29 @@ function listExtractionTypeNames() {
   ]);
 }
 function registerKnowledgeExtractionResources(server) {
+  const resource = getKnowledgeResourceEntry(KNOWLEDGE_EXTRACTION_TYPES_RESOURCE_URI);
+  if (!resource) {
+    throw new Error("Knowledge extraction resource metadata is missing.");
+  }
   server.registerResource(
-    "knowledge-extraction-types",
+    resource.name,
     KNOWLEDGE_EXTRACTION_TYPES_RESOURCE_URI,
     {
-      title: "Knowledge Extraction Types",
-      description: "Canonical registry of knowledge types supported by the extraction workflow.",
-      mimeType: "application/json"
+      title: resource.title,
+      description: resource.description,
+      mimeType: resource.mimeType
     },
-    async (uri) => createJsonResourceContent(
-      uri.href,
-      JSON.stringify(buildKnowledgeExtractionTypeIndexDocument(), null, 2)
-    )
+    async (uri) => ({
+      contents: [(await readKnowledgeResourceDocument(uri.href)).content]
+    })
   );
   server.registerResource(
     "knowledge-extraction-schema",
     new ResourceTemplate(KNOWLEDGE_EXTRACTION_SCHEMA_RESOURCE_URI, {
       list: async () => ({
-        resources: listKnowledgeExtractionResourceTypes().map((definition) => ({
-          uri: `ez-know://extraction/schema/${definition.collection}`,
-          name: definition.collection,
-          title: `${definition.title} Extraction Schema`,
-          description: `Runtime schema discovery for ${definition.title.toLowerCase()}.`,
-          mimeType: "application/json"
-        }))
+        resources: listKnowledgeResourceTemplateResources(
+          KNOWLEDGE_EXTRACTION_SCHEMA_RESOURCE_URI
+        )
       }),
       complete: {
         type: async (value) => listExtractionTypeNames().filter(
@@ -3103,29 +3332,17 @@ function registerKnowledgeExtractionResources(server) {
       description: "Runtime JSON-schema discovery for a supported knowledge type.",
       mimeType: "application/json"
     },
-    async (_uri, variables) => {
-      const type = variables.type;
-      if (typeof type !== "string" || type.length === 0) {
-        throw new Error("Resource type is required.");
-      }
-      const document = buildKnowledgeExtractionSchemaDocument(type);
-      return createJsonResourceContent(
-        `ez-know://extraction/schema/${document.type.collection}`,
-        JSON.stringify(document, null, 2)
-      );
-    }
+    async (uri) => ({
+      contents: [(await readKnowledgeResourceDocument(uri.href)).content]
+    })
   );
   server.registerResource(
     "knowledge-extraction-guide",
     new ResourceTemplate(KNOWLEDGE_EXTRACTION_GUIDE_RESOURCE_URI, {
       list: async () => ({
-        resources: listKnowledgeExtractionResourceTypes().map((definition) => ({
-          uri: `ez-know://extraction/guide/${definition.collection}`,
-          name: definition.collection,
-          title: `${definition.title} Extraction Guide`,
-          description: `Checked-in extraction guidance for ${definition.title.toLowerCase()}.`,
-          mimeType: "text/markdown"
-        }))
+        resources: listKnowledgeResourceTemplateResources(
+          KNOWLEDGE_EXTRACTION_GUIDE_RESOURCE_URI
+        )
       }),
       complete: {
         type: async (value) => listExtractionTypeNames().filter(
@@ -3138,17 +3355,9 @@ function registerKnowledgeExtractionResources(server) {
       description: "Checked-in Markdown guidance for a supported knowledge type.",
       mimeType: "text/markdown"
     },
-    async (_uri, variables) => {
-      const type = variables.type;
-      if (typeof type !== "string" || type.length === 0) {
-        throw new Error("Resource type is required.");
-      }
-      const document = await buildKnowledgeExtractionGuideDocument(type);
-      return createMarkdownResourceContent(
-        `ez-know://extraction/guide/${document.type.collection}`,
-        document.markdown
-      );
-    }
+    async (uri) => ({
+      contents: [(await readKnowledgeResourceDocument(uri.href)).content]
+    })
   );
 }
 
@@ -3212,6 +3421,104 @@ function registerKnowledgeGraphTool(server, getStore) {
   );
 }
 
+// packages/mcp/src/tools/legacy-resource-tools.ts
+import * as z8 from "zod/v4";
+function createTextToolResult(payload) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(payload, null, 2)
+      }
+    ]
+  };
+}
+function serializeResourceError(error, uri) {
+  if (error instanceof KnowledgeResourceNotFoundError || error instanceof KnowledgeResourceUriError) {
+    return {
+      error: {
+        code: error.code,
+        message: error.message,
+        uri: error.uri
+      }
+    };
+  }
+  if (error instanceof Error) {
+    return {
+      error: {
+        code: "RESOURCE_READ_FAILED",
+        message: error.message,
+        uri
+      }
+    };
+  }
+  return {
+    error: {
+      code: "RESOURCE_READ_FAILED",
+      message: "Unknown resource read failure.",
+      uri
+    }
+  };
+}
+function isLegacyResourceToolsEnabled(value = process.env.EZ_KNOW_LEGACY_RESOURCES) {
+  if (value === void 0) {
+    return false;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (normalized.length === 0) {
+    return false;
+  }
+  return !["0", "false", "off", "no"].includes(normalized);
+}
+function registerLegacyResourceTools(server) {
+  server.registerTool(
+    "list_mcp_resources",
+    {
+      title: "Legacy MCP Resource List",
+      description: "Lists the ez-know resources exposed through the legacy tool fallback.",
+      inputSchema: z8.object({})
+    },
+    async () => createTextToolResult({
+      resources: listKnowledgeResourceEntries()
+    })
+  );
+  server.registerTool(
+    "list_mcp_resource_templates",
+    {
+      title: "Legacy MCP Resource Templates",
+      description: "Lists the ez-know resource templates exposed through the legacy tool fallback.",
+      inputSchema: z8.object({})
+    },
+    async () => createTextToolResult({
+      resourceTemplates: listKnowledgeResourceTemplateEntries()
+    })
+  );
+  server.registerTool(
+    "read_mcp_resource",
+    {
+      title: "Legacy MCP Resource Read",
+      description: "Reads a single ez-know resource by URI through the legacy tool fallback.",
+      inputSchema: z8.object({
+        uri: z8.string().min(1)
+      })
+    },
+    async (input) => {
+      const parsedInput = z8.object({ uri: z8.string().min(1) }).parse(input);
+      try {
+        const result = await readKnowledgeResourceDocument(parsedInput.uri);
+        return createTextToolResult({
+          resource: result.resource,
+          contents: [result.content]
+        });
+      } catch (error) {
+        return createTextToolResult(
+          serializeResourceError(error, parsedInput.uri)
+        );
+      }
+    }
+  );
+}
+
 // packages/mcp/src/tools/knowledge-patch-apply.ts
 function registerKnowledgePatchApplyTool(server) {
   server.registerTool(
@@ -3268,43 +3575,29 @@ function registerKnowledgePatchTool(server) {
 
 // packages/mcp/src/resources/knowledge-schema.ts
 import { ResourceTemplate as ResourceTemplate2 } from "@modelcontextprotocol/server";
-function createJsonResourceContent2(uri, text) {
-  return {
-    contents: [
-      {
-        uri,
-        mimeType: "application/json",
-        text
-      }
-    ]
-  };
-}
 function registerKnowledgeSchemaResources(server) {
+  const resource = getKnowledgeResourceEntry(KNOWLEDGE_SCHEMA_RESOURCE_URI);
+  if (!resource) {
+    throw new Error("Knowledge schema resource metadata is missing.");
+  }
   server.registerResource(
-    "knowledge-schema",
+    resource.name,
     KNOWLEDGE_SCHEMA_RESOURCE_URI,
     {
-      title: "Knowledge GraphQL Schema",
-      description: "Canonical runtime GraphQL schema discovery payload for the knowledge layer.",
-      mimeType: "application/json"
+      title: resource.title,
+      description: resource.description,
+      mimeType: resource.mimeType
     },
-    async (uri) => createJsonResourceContent2(
-      uri.href,
-      createKnowledgeSchemaResourceText(knowledgeGraphSchema)
-    )
+    async (uri) => ({
+      contents: [(await readKnowledgeResourceDocument(uri.href)).content]
+    })
   );
   server.registerResource(
     "knowledge-schema-lookup",
     new ResourceTemplate2(KNOWLEDGE_SCHEMA_LOOKUP_URI, {
       list: async () => ({
-        resources: listKnowledgeSchemaTargets(knowledgeGraphSchema).map(
-          (target) => ({
-            uri: `knowledge-schema://lookup/${target}`,
-            name: target,
-            title: `Knowledge schema lookup: ${target}`,
-            description: target === "Query" ? "Focused lookup of the root query fields." : `Focused lookup of ${target}.`,
-            mimeType: "application/json"
-          })
+        resources: listKnowledgeResourceTemplateResources(
+          KNOWLEDGE_SCHEMA_LOOKUP_URI
         )
       }),
       complete: {
@@ -3318,27 +3611,19 @@ function registerKnowledgeSchemaResources(server) {
       description: "Focused runtime GraphQL schema lookup for a type name, root field, or Query.",
       mimeType: "application/json"
     },
-    async (_uri, variables) => {
-      const target = variables.target;
-      if (typeof target !== "string" || target.length === 0) {
-        throw new Error("Resource target is required.");
-      }
-      return createJsonResourceContent2(
-        `knowledge-schema://lookup/${target}`,
-        createKnowledgeSchemaLookupText(knowledgeGraphSchema, target)
-      );
-    }
+    async (uri) => ({
+      contents: [(await readKnowledgeResourceDocument(uri.href)).content]
+    })
   );
 }
 
 // packages/mcp/src/run.ts
-async function startMcpServer() {
-  const server = new McpServer({
-    name: "ez-know",
-    version: "0.1.0"
-  });
+function registerMcpServerCapabilities(server) {
   registerKnowledgeSchemaResources(server);
   registerKnowledgeExtractionResources(server);
+  if (isLegacyResourceToolsEnabled()) {
+    registerLegacyResourceTools(server);
+  }
   registerKnowledgeGraphTool(server, async () => {
     const effectiveState = await loadEffectiveKnowledgeStoreFromEnv(
       process.env.EZ_KNOW_ROOT
@@ -3348,6 +3633,13 @@ async function startMcpServer() {
   registerKnowledgePatchTool(server);
   registerKnowledgePatchApplyTool(server);
   registerCompareScopeWithEvidenceTool(server);
+}
+async function startMcpServer() {
+  const server = new McpServer({
+    name: "ez-know",
+    version: "0.1.0"
+  });
+  registerMcpServerCapabilities(server);
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }