@matrajs/mcp 1.0.0

package/dist/index.cjs

@@ -0,0 +1,240 @@
+'use strict';
+
+// src/index.ts
+var PARSE_ERROR = -32700;
+var INVALID_REQUEST = -32600;
+var METHOD_NOT_FOUND = -32601;
+var INVALID_PARAMS = -32602;
+var RpcError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+  code;
+};
+var PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+var LATEST = PROTOCOL_VERSIONS[0];
+var tokens = (text) => text.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((word) => word.length > 1);
+function searchDocs(docs, query, limit = 5) {
+  const terms = tokens(query);
+  if (!terms.length) return [];
+  const hits = [];
+  for (const doc of docs) {
+    const title = doc.title.toLowerCase();
+    const body = doc.text.toLowerCase();
+    let score = 0;
+    let missing = false;
+    for (const term of terms) {
+      const inTitle = title.includes(term) ? 3 : 0;
+      let inBody = 0;
+      let at = body.indexOf(term);
+      while (at !== -1 && inBody < 20) {
+        inBody++;
+        at = body.indexOf(term, at + term.length);
+      }
+      if (!inTitle && !inBody) {
+        missing = true;
+        break;
+      }
+      score += inTitle + inBody;
+    }
+    if (missing) continue;
+    hits.push({ doc, score, snippet: snippetFor(doc.text, terms[0]) });
+  }
+  hits.sort((a, b) => b.score - a.score || a.doc.title.localeCompare(b.doc.title));
+  return hits.slice(0, Math.max(1, Math.min(limit, 20)));
+}
+function snippetFor(text, term) {
+  const lower = text.toLowerCase();
+  const at = lower.indexOf(term);
+  if (at === -1) return text.slice(0, 200).replace(/\s+/g, " ").trim();
+  const start = Math.max(0, at - 120);
+  const end = Math.min(text.length, at + 200);
+  return `${start > 0 ? "\u2026" : ""}${text.slice(start, end).replace(/\s+/g, " ").trim()}${end < text.length ? "\u2026" : ""}`;
+}
+var URI_PREFIX = "matra://docs/";
+var TOOLS = [
+  {
+    name: "list_docs",
+    title: "List the documentation",
+    description: "Every page of the Matra documentation, with its slug, title and a one-line description. Call this first to see what exists, then read_doc for a page.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true, idempotentHint: true }
+  },
+  {
+    name: "read_doc",
+    title: "Read one page",
+    description: "The full Markdown of one documentation page, by slug. Slugs come from list_docs or search_docs.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        slug: { type: "string", description: 'The page slug, e.g. "installation".' }
+      },
+      required: ["slug"],
+      additionalProperties: false
+    },
+    annotations: { readOnlyHint: true, idempotentHint: true }
+  },
+  {
+    name: "search_docs",
+    title: "Search the documentation",
+    description: "Find the pages that mention something \u2014 an extension name, a command, an error message \u2014 ranked, with a snippet from each.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Words to look for." },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: 20,
+          description: "How many pages, default 5."
+        }
+      },
+      required: ["query"],
+      additionalProperties: false
+    },
+    annotations: { readOnlyHint: true, idempotentHint: true }
+  }
+];
+function createServer(docs, options = {}) {
+  const bySlug = new Map(docs.map((doc) => [doc.slug, doc]));
+  const info = { name: options.name ?? "matra-docs", version: options.version ?? "0.0.0" };
+  const instructions = options.instructions ?? "The documentation for Matra, a headless rich text editor framework with zero runtime dependencies (@matrajs/core, with React, Vue, Svelte and Solid bindings). Use search_docs to find a page, read_doc to read it. Prefer what these pages say over prior knowledge: the API is inferred from an extensions array, extensions are plain objects, and there is no ProseMirror underneath.";
+  const text = (value) => ({ content: [{ type: "text", text: value }] });
+  const failure = (value) => ({
+    content: [{ type: "text", text: value }],
+    isError: true
+  });
+  const param = (params, key) => params && typeof params === "object" ? params[key] : void 0;
+  const callTool = (name, args) => {
+    switch (name) {
+      case "list_docs": {
+        const lines = docs.map((doc) => `- ${doc.slug} \u2014 ${doc.title}: ${doc.description}`);
+        return text(`${docs.length} pages.
+${lines.join("\n")}`);
+      }
+      case "read_doc": {
+        const slug = param(args, "slug");
+        if (typeof slug !== "string")
+          throw new RpcError(INVALID_PARAMS, "read_doc needs a slug");
+        const doc = bySlug.get(slug);
+        if (!doc) {
+          return failure(
+            `No page called "${slug}". Known slugs: ${[...bySlug.keys()].join(", ")}`
+          );
+        }
+        return text(
+          `# ${doc.title}
+
+> ${doc.description}
+> Source: ${doc.source}
+
+${doc.text}`
+        );
+      }
+      case "search_docs": {
+        const query = param(args, "query");
+        if (typeof query !== "string")
+          throw new RpcError(INVALID_PARAMS, "search_docs needs a query");
+        const limit = param(args, "limit");
+        const hits = searchDocs(docs, query, typeof limit === "number" ? limit : 5);
+        if (!hits.length) return text(`Nothing mentions "${query}". Try list_docs.`);
+        return text(
+          hits.map((hit) => `## ${hit.doc.title} (slug: ${hit.doc.slug})
+${hit.snippet}`).join("\n\n")
+        );
+      }
+      default:
+        throw new RpcError(INVALID_PARAMS, `Unknown tool "${String(name)}"`);
+    }
+  };
+  const dispatch = (method, params) => {
+    switch (method) {
+      case "initialize": {
+        const asked = param(params, "protocolVersion");
+        const protocolVersion = typeof asked === "string" && PROTOCOL_VERSIONS.includes(asked) ? asked : LATEST;
+        return {
+          protocolVersion,
+          capabilities: { tools: { listChanged: false }, resources: { listChanged: false } },
+          serverInfo: { ...info, title: "Matra docs" },
+          instructions
+        };
+      }
+      case "ping":
+        return {};
+      case "tools/list":
+        return { tools: TOOLS };
+      case "tools/call":
+        return callTool(param(params, "name"), param(params, "arguments"));
+      case "resources/list":
+        return {
+          resources: docs.map((doc) => ({
+            uri: `${URI_PREFIX}${doc.slug}`,
+            name: doc.slug,
+            title: doc.title,
+            description: doc.description,
+            mimeType: "text/markdown"
+          }))
+        };
+      case "resources/templates/list":
+        return { resourceTemplates: [] };
+      case "resources/read": {
+        const uri = param(params, "uri");
+        if (typeof uri !== "string" || !uri.startsWith(URI_PREFIX)) {
+          throw new RpcError(INVALID_PARAMS, `Not a matra:// documentation URI: ${String(uri)}`);
+        }
+        const doc = bySlug.get(uri.slice(URI_PREFIX.length));
+        if (!doc) throw new RpcError(INVALID_PARAMS, `No page at ${uri}`);
+        return { contents: [{ uri, mimeType: "text/markdown", text: doc.text }] };
+      }
+      case "prompts/list":
+        return { prompts: [] };
+      case "logging/setLevel":
+        return {};
+      default:
+        throw new RpcError(METHOD_NOT_FOUND, `Method not found: ${method}`);
+    }
+  };
+  const handle = (message) => {
+    const request = message;
+    const id = request && typeof request === "object" && "id" in request ? request.id ?? null : null;
+    if (!request || typeof request !== "object" || request.jsonrpc !== "2.0" || typeof request.method !== "string") {
+      return {
+        jsonrpc: "2.0",
+        id,
+        error: { code: INVALID_REQUEST, message: "Not a JSON-RPC 2.0 request" }
+      };
+    }
+    const isNotification = !("id" in request) || request.id === void 0;
+    if (request.method.startsWith("notifications/")) return null;
+    try {
+      const result = dispatch(request.method, request.params);
+      return isNotification ? null : { jsonrpc: "2.0", id, result };
+    } catch (error) {
+      if (isNotification) return null;
+      const code = error instanceof RpcError ? error.code : -32603;
+      const message2 = error instanceof Error ? error.message : String(error);
+      return { jsonrpc: "2.0", id, error: { code, message: message2 } };
+    }
+  };
+  const handleRaw = (json) => {
+    let parsed;
+    try {
+      parsed = JSON.parse(json);
+    } catch {
+      return { jsonrpc: "2.0", id: null, error: { code: PARSE_ERROR, message: "Parse error" } };
+    }
+    if (Array.isArray(parsed)) {
+      const replies = parsed.map(handle).filter((reply) => reply !== null);
+      return replies.length ? replies : null;
+    }
+    return handle(parsed);
+  };
+  return { handle, handleRaw, docs };
+}
+
+exports.PROTOCOL_VERSIONS = PROTOCOL_VERSIONS;
+exports.createServer = createServer;
+exports.searchDocs = searchDocs;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["message"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * The Matra documentation, served over the Model Context Protocol.\n *\n * MCP is JSON-RPC 2.0 with a handshake and a small vocabulary — tools,\n * resources, prompts — that Claude, Cursor, Codex and the rest all speak. This\n * module is the protocol half: it takes one message and returns one reply,\n * and knows nothing about where either came from. The transports — stdio and\n * HTTP — are in `cli.ts`, and a test drives this without either.\n *\n * Written against the spec directly, with no SDK, because every other package\n * here has zero runtime dependencies and the one that exists to be installed\n * with `npx` should not be the exception.\n */\n\n/** One page of documentation. */\nexport interface Doc {\n  /** URL-safe, unique: `installation`, `engine`, `changelog`. */\n  slug: string\n  title: string\n  description: string\n  /** Where it came from — a path in the repository, or a page on the site. */\n  source: string\n  /** Markdown. */\n  text: string\n}\n\nexport interface ServerOptions {\n  name?: string\n  version?: string\n  /** What a client is told about this server when it connects. */\n  instructions?: string\n}\n\n// --- JSON-RPC ---------------------------------------------------------------\n\nexport type JsonRpcId = string | number | null\n\nexport interface JsonRpcRequest {\n  jsonrpc: '2.0'\n  id?: JsonRpcId\n  method: string\n  params?: Record<string, unknown>\n}\n\nexport interface JsonRpcResponse {\n  jsonrpc: '2.0'\n  id: JsonRpcId\n  result?: unknown\n  error?: { code: number; message: string; data?: unknown }\n}\n\nconst PARSE_ERROR = -32700\nconst INVALID_REQUEST = -32600\nconst METHOD_NOT_FOUND = -32601\nconst INVALID_PARAMS = -32602\n\nclass RpcError extends Error {\n  constructor(\n    readonly code: number,\n    message: string,\n  ) {\n    super(message)\n  }\n}\n\n/** Protocol revisions this server can speak, newest first. */\nexport const PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'] as const\n\nconst LATEST = PROTOCOL_VERSIONS[0]\n\n// --- searching ----------------------------------------------------------------\n\nconst tokens = (text: string): string[] =>\n  text\n    .toLowerCase()\n    .split(/[^\\p{L}\\p{N}]+/u)\n    .filter((word) => word.length > 1)\n\ninterface Hit {\n  doc: Doc\n  score: number\n  snippet: string\n}\n\n/**\n * Rank pages for a query.\n *\n * Term frequency, with the title worth more than the body and every term\n * required to appear somewhere. Small enough to read, good enough for twenty\n * pages of documentation, and it needs no index built in advance.\n */\nexport function searchDocs(docs: readonly Doc[], query: string, limit = 5): Hit[] {\n  const terms = tokens(query)\n  if (!terms.length) return []\n  const hits: Hit[] = []\n  for (const doc of docs) {\n    const title = doc.title.toLowerCase()\n    const body = doc.text.toLowerCase()\n    let score = 0\n    let missing = false\n    for (const term of terms) {\n      const inTitle = title.includes(term) ? 3 : 0\n      let inBody = 0\n      let at = body.indexOf(term)\n      while (at !== -1 && inBody < 20) {\n        inBody++\n        at = body.indexOf(term, at + term.length)\n      }\n      if (!inTitle && !inBody) {\n        missing = true\n        break\n      }\n      score += inTitle + inBody\n    }\n    if (missing) continue\n    hits.push({ doc, score, snippet: snippetFor(doc.text, terms[0] as string) })\n  }\n  hits.sort((a, b) => b.score - a.score || a.doc.title.localeCompare(b.doc.title))\n  return hits.slice(0, Math.max(1, Math.min(limit, 20)))\n}\n\n/** A line or two around the first place a term appears. */\nfunction snippetFor(text: string, term: string): string {\n  const lower = text.toLowerCase()\n  const at = lower.indexOf(term)\n  if (at === -1) return text.slice(0, 200).replace(/\\s+/g, ' ').trim()\n  const start = Math.max(0, at - 120)\n  const end = Math.min(text.length, at + 200)\n  return `${start > 0 ? '…' : ''}${text.slice(start, end).replace(/\\s+/g, ' ').trim()}${end < text.length ? '…' : ''}`\n}\n\n// --- the server --------------------------------------------------------------\n\nconst URI_PREFIX = 'matra://docs/'\n\nconst TOOLS = [\n  {\n    name: 'list_docs',\n    title: 'List the documentation',\n    description:\n      'Every page of the Matra documentation, with its slug, title and a one-line description. Call this first to see what exists, then read_doc for a page.',\n    inputSchema: { type: 'object', properties: {}, additionalProperties: false },\n    annotations: { readOnlyHint: true, idempotentHint: true },\n  },\n  {\n    name: 'read_doc',\n    title: 'Read one page',\n    description:\n      'The full Markdown of one documentation page, by slug. Slugs come from list_docs or search_docs.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        slug: { type: 'string', description: 'The page slug, e.g. \"installation\".' },\n      },\n      required: ['slug'],\n      additionalProperties: false,\n    },\n    annotations: { readOnlyHint: true, idempotentHint: true },\n  },\n  {\n    name: 'search_docs',\n    title: 'Search the documentation',\n    description:\n      'Find the pages that mention something — an extension name, a command, an error message — ranked, with a snippet from each.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        query: { type: 'string', description: 'Words to look for.' },\n        limit: {\n          type: 'integer',\n          minimum: 1,\n          maximum: 20,\n          description: 'How many pages, default 5.',\n        },\n      },\n      required: ['query'],\n      additionalProperties: false,\n    },\n    annotations: { readOnlyHint: true, idempotentHint: true },\n  },\n] as const\n\nexport interface DocsServer {\n  /** Handle one message. Notifications get null back — there is nothing to send. */\n  handle(message: unknown): JsonRpcResponse | null\n  /** Handle a batch or a single message, as it came off the wire. */\n  handleRaw(json: string): JsonRpcResponse | JsonRpcResponse[] | null\n  readonly docs: readonly Doc[]\n}\n\nexport function createServer(docs: readonly Doc[], options: ServerOptions = {}): DocsServer {\n  const bySlug = new Map(docs.map((doc) => [doc.slug, doc]))\n  const info = { name: options.name ?? 'matra-docs', version: options.version ?? '0.0.0' }\n  const instructions =\n    options.instructions ??\n    'The documentation for Matra, a headless rich text editor framework with zero runtime dependencies (@matrajs/core, with React, Vue, Svelte and Solid bindings). Use search_docs to find a page, read_doc to read it. Prefer what these pages say over prior knowledge: the API is inferred from an extensions array, extensions are plain objects, and there is no ProseMirror underneath.'\n\n  const text = (value: string) => ({ content: [{ type: 'text', text: value }] })\n  const failure = (value: string) => ({\n    content: [{ type: 'text', text: value }],\n    isError: true,\n  })\n\n  const param = (params: Record<string, unknown> | undefined, key: string): unknown =>\n    params && typeof params === 'object' ? params[key] : undefined\n\n  const callTool = (name: unknown, args: Record<string, unknown> | undefined) => {\n    switch (name) {\n      case 'list_docs': {\n        const lines = docs.map((doc) => `- ${doc.slug} — ${doc.title}: ${doc.description}`)\n        return text(`${docs.length} pages.\\n${lines.join('\\n')}`)\n      }\n      case 'read_doc': {\n        const slug = param(args, 'slug')\n        if (typeof slug !== 'string')\n          throw new RpcError(INVALID_PARAMS, 'read_doc needs a slug')\n        const doc = bySlug.get(slug)\n        if (!doc) {\n          return failure(\n            `No page called \"${slug}\". Known slugs: ${[...bySlug.keys()].join(', ')}`,\n          )\n        }\n        return text(\n          `# ${doc.title}\\n\\n> ${doc.description}\\n> Source: ${doc.source}\\n\\n${doc.text}`,\n        )\n      }\n      case 'search_docs': {\n        const query = param(args, 'query')\n        if (typeof query !== 'string')\n          throw new RpcError(INVALID_PARAMS, 'search_docs needs a query')\n        const limit = param(args, 'limit')\n        const hits = searchDocs(docs, query, typeof limit === 'number' ? limit : 5)\n        if (!hits.length) return text(`Nothing mentions \"${query}\". Try list_docs.`)\n        return text(\n          hits\n            .map((hit) => `## ${hit.doc.title} (slug: ${hit.doc.slug})\\n${hit.snippet}`)\n            .join('\\n\\n'),\n        )\n      }\n      default:\n        throw new RpcError(INVALID_PARAMS, `Unknown tool \"${String(name)}\"`)\n    }\n  }\n\n  const dispatch = (method: string, params: Record<string, unknown> | undefined): unknown => {\n    switch (method) {\n      case 'initialize': {\n        const asked = param(params, 'protocolVersion')\n        const protocolVersion =\n          typeof asked === 'string' && (PROTOCOL_VERSIONS as readonly string[]).includes(asked)\n            ? asked\n            : LATEST\n        return {\n          protocolVersion,\n          capabilities: { tools: { listChanged: false }, resources: { listChanged: false } },\n          serverInfo: { ...info, title: 'Matra docs' },\n          instructions,\n        }\n      }\n      case 'ping':\n        return {}\n      case 'tools/list':\n        return { tools: TOOLS }\n      case 'tools/call':\n        return callTool(param(params, 'name'), param(params, 'arguments') as never)\n      case 'resources/list':\n        return {\n          resources: docs.map((doc) => ({\n            uri: `${URI_PREFIX}${doc.slug}`,\n            name: doc.slug,\n            title: doc.title,\n            description: doc.description,\n            mimeType: 'text/markdown',\n          })),\n        }\n      case 'resources/templates/list':\n        return { resourceTemplates: [] }\n      case 'resources/read': {\n        const uri = param(params, 'uri')\n        if (typeof uri !== 'string' || !uri.startsWith(URI_PREFIX)) {\n          throw new RpcError(INVALID_PARAMS, `Not a matra:// documentation URI: ${String(uri)}`)\n        }\n        const doc = bySlug.get(uri.slice(URI_PREFIX.length))\n        if (!doc) throw new RpcError(INVALID_PARAMS, `No page at ${uri}`)\n        return { contents: [{ uri, mimeType: 'text/markdown', text: doc.text }] }\n      }\n      case 'prompts/list':\n        return { prompts: [] }\n      case 'logging/setLevel':\n        return {}\n      default:\n        throw new RpcError(METHOD_NOT_FOUND, `Method not found: ${method}`)\n    }\n  }\n\n  const handle = (message: unknown): JsonRpcResponse | null => {\n    const request = message as Partial<JsonRpcRequest> | null\n    const id: JsonRpcId =\n      request && typeof request === 'object' && 'id' in request ? (request.id ?? null) : null\n    if (\n      !request ||\n      typeof request !== 'object' ||\n      request.jsonrpc !== '2.0' ||\n      typeof request.method !== 'string'\n    ) {\n      return {\n        jsonrpc: '2.0',\n        id,\n        error: { code: INVALID_REQUEST, message: 'Not a JSON-RPC 2.0 request' },\n      }\n    }\n    // A notification carries no id and gets no reply.\n    const isNotification = !('id' in request) || request.id === undefined\n    if (request.method.startsWith('notifications/')) return null\n    try {\n      const result = dispatch(request.method, request.params)\n      return isNotification ? null : { jsonrpc: '2.0', id, result }\n    } catch (error) {\n      if (isNotification) return null\n      const code = error instanceof RpcError ? error.code : -32603\n      const message = error instanceof Error ? error.message : String(error)\n      return { jsonrpc: '2.0', id, error: { code, message } }\n    }\n  }\n\n  const handleRaw = (json: string): JsonRpcResponse | JsonRpcResponse[] | null => {\n    let parsed: unknown\n    try {\n      parsed = JSON.parse(json)\n    } catch {\n      return { jsonrpc: '2.0', id: null, error: { code: PARSE_ERROR, message: 'Parse error' } }\n    }\n    if (Array.isArray(parsed)) {\n      const replies = parsed\n        .map(handle)\n        .filter((reply): reply is JsonRpcResponse => reply !== null)\n      return replies.length ? replies : null\n    }\n    return handle(parsed)\n  }\n\n  return { handle, handleRaw, docs }\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,72 @@
+/**
+ * The Matra documentation, served over the Model Context Protocol.
+ *
+ * MCP is JSON-RPC 2.0 with a handshake and a small vocabulary — tools,
+ * resources, prompts — that Claude, Cursor, Codex and the rest all speak. This
+ * module is the protocol half: it takes one message and returns one reply,
+ * and knows nothing about where either came from. The transports — stdio and
+ * HTTP — are in `cli.ts`, and a test drives this without either.
+ *
+ * Written against the spec directly, with no SDK, because every other package
+ * here has zero runtime dependencies and the one that exists to be installed
+ * with `npx` should not be the exception.
+ */
+/** One page of documentation. */
+interface Doc {
+    /** URL-safe, unique: `installation`, `engine`, `changelog`. */
+    slug: string;
+    title: string;
+    description: string;
+    /** Where it came from — a path in the repository, or a page on the site. */
+    source: string;
+    /** Markdown. */
+    text: string;
+}
+interface ServerOptions {
+    name?: string;
+    version?: string;
+    /** What a client is told about this server when it connects. */
+    instructions?: string;
+}
+type JsonRpcId = string | number | null;
+interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id?: JsonRpcId;
+    method: string;
+    params?: Record<string, unknown>;
+}
+interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: JsonRpcId;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+/** Protocol revisions this server can speak, newest first. */
+declare const PROTOCOL_VERSIONS: readonly ["2025-06-18", "2025-03-26", "2024-11-05"];
+interface Hit {
+    doc: Doc;
+    score: number;
+    snippet: string;
+}
+/**
+ * Rank pages for a query.
+ *
+ * Term frequency, with the title worth more than the body and every term
+ * required to appear somewhere. Small enough to read, good enough for twenty
+ * pages of documentation, and it needs no index built in advance.
+ */
+declare function searchDocs(docs: readonly Doc[], query: string, limit?: number): Hit[];
+interface DocsServer {
+    /** Handle one message. Notifications get null back — there is nothing to send. */
+    handle(message: unknown): JsonRpcResponse | null;
+    /** Handle a batch or a single message, as it came off the wire. */
+    handleRaw(json: string): JsonRpcResponse | JsonRpcResponse[] | null;
+    readonly docs: readonly Doc[];
+}
+declare function createServer(docs: readonly Doc[], options?: ServerOptions): DocsServer;
+
+export { type Doc, type DocsServer, type JsonRpcId, type JsonRpcRequest, type JsonRpcResponse, PROTOCOL_VERSIONS, type ServerOptions, createServer, searchDocs };

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The Matra documentation, served over the Model Context Protocol.
+ *
+ * MCP is JSON-RPC 2.0 with a handshake and a small vocabulary — tools,
+ * resources, prompts — that Claude, Cursor, Codex and the rest all speak. This
+ * module is the protocol half: it takes one message and returns one reply,
+ * and knows nothing about where either came from. The transports — stdio and
+ * HTTP — are in `cli.ts`, and a test drives this without either.
+ *
+ * Written against the spec directly, with no SDK, because every other package
+ * here has zero runtime dependencies and the one that exists to be installed
+ * with `npx` should not be the exception.
+ */
+/** One page of documentation. */
+interface Doc {
+    /** URL-safe, unique: `installation`, `engine`, `changelog`. */
+    slug: string;
+    title: string;
+    description: string;
+    /** Where it came from — a path in the repository, or a page on the site. */
+    source: string;
+    /** Markdown. */
+    text: string;
+}
+interface ServerOptions {
+    name?: string;
+    version?: string;
+    /** What a client is told about this server when it connects. */
+    instructions?: string;
+}
+type JsonRpcId = string | number | null;
+interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id?: JsonRpcId;
+    method: string;
+    params?: Record<string, unknown>;
+}
+interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: JsonRpcId;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+/** Protocol revisions this server can speak, newest first. */
+declare const PROTOCOL_VERSIONS: readonly ["2025-06-18", "2025-03-26", "2024-11-05"];
+interface Hit {
+    doc: Doc;
+    score: number;
+    snippet: string;
+}
+/**
+ * Rank pages for a query.
+ *
+ * Term frequency, with the title worth more than the body and every term
+ * required to appear somewhere. Small enough to read, good enough for twenty
+ * pages of documentation, and it needs no index built in advance.
+ */
+declare function searchDocs(docs: readonly Doc[], query: string, limit?: number): Hit[];
+interface DocsServer {
+    /** Handle one message. Notifications get null back — there is nothing to send. */
+    handle(message: unknown): JsonRpcResponse | null;
+    /** Handle a batch or a single message, as it came off the wire. */
+    handleRaw(json: string): JsonRpcResponse | JsonRpcResponse[] | null;
+    readonly docs: readonly Doc[];
+}
+declare function createServer(docs: readonly Doc[], options?: ServerOptions): DocsServer;
+
+export { type Doc, type DocsServer, type JsonRpcId, type JsonRpcRequest, type JsonRpcResponse, PROTOCOL_VERSIONS, type ServerOptions, createServer, searchDocs };

package/dist/index.js

@@ -0,0 +1,236 @@
+// src/index.ts
+var PARSE_ERROR = -32700;
+var INVALID_REQUEST = -32600;
+var METHOD_NOT_FOUND = -32601;
+var INVALID_PARAMS = -32602;
+var RpcError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+  code;
+};
+var PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+var LATEST = PROTOCOL_VERSIONS[0];
+var tokens = (text) => text.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((word) => word.length > 1);
+function searchDocs(docs, query, limit = 5) {
+  const terms = tokens(query);
+  if (!terms.length) return [];
+  const hits = [];
+  for (const doc of docs) {
+    const title = doc.title.toLowerCase();
+    const body = doc.text.toLowerCase();
+    let score = 0;
+    let missing = false;
+    for (const term of terms) {
+      const inTitle = title.includes(term) ? 3 : 0;
+      let inBody = 0;
+      let at = body.indexOf(term);
+      while (at !== -1 && inBody < 20) {
+        inBody++;
+        at = body.indexOf(term, at + term.length);
+      }
+      if (!inTitle && !inBody) {
+        missing = true;
+        break;
+      }
+      score += inTitle + inBody;
+    }
+    if (missing) continue;
+    hits.push({ doc, score, snippet: snippetFor(doc.text, terms[0]) });
+  }
+  hits.sort((a, b) => b.score - a.score || a.doc.title.localeCompare(b.doc.title));
+  return hits.slice(0, Math.max(1, Math.min(limit, 20)));
+}
+function snippetFor(text, term) {
+  const lower = text.toLowerCase();
+  const at = lower.indexOf(term);
+  if (at === -1) return text.slice(0, 200).replace(/\s+/g, " ").trim();
+  const start = Math.max(0, at - 120);
+  const end = Math.min(text.length, at + 200);
+  return `${start > 0 ? "\u2026" : ""}${text.slice(start, end).replace(/\s+/g, " ").trim()}${end < text.length ? "\u2026" : ""}`;
+}
+var URI_PREFIX = "matra://docs/";
+var TOOLS = [
+  {
+    name: "list_docs",
+    title: "List the documentation",
+    description: "Every page of the Matra documentation, with its slug, title and a one-line description. Call this first to see what exists, then read_doc for a page.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true, idempotentHint: true }
+  },
+  {
+    name: "read_doc",
+    title: "Read one page",
+    description: "The full Markdown of one documentation page, by slug. Slugs come from list_docs or search_docs.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        slug: { type: "string", description: 'The page slug, e.g. "installation".' }
+      },
+      required: ["slug"],
+      additionalProperties: false
+    },
+    annotations: { readOnlyHint: true, idempotentHint: true }
+  },
+  {
+    name: "search_docs",
+    title: "Search the documentation",
+    description: "Find the pages that mention something \u2014 an extension name, a command, an error message \u2014 ranked, with a snippet from each.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Words to look for." },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: 20,
+          description: "How many pages, default 5."
+        }
+      },
+      required: ["query"],
+      additionalProperties: false
+    },
+    annotations: { readOnlyHint: true, idempotentHint: true }
+  }
+];
+function createServer(docs, options = {}) {
+  const bySlug = new Map(docs.map((doc) => [doc.slug, doc]));
+  const info = { name: options.name ?? "matra-docs", version: options.version ?? "0.0.0" };
+  const instructions = options.instructions ?? "The documentation for Matra, a headless rich text editor framework with zero runtime dependencies (@matrajs/core, with React, Vue, Svelte and Solid bindings). Use search_docs to find a page, read_doc to read it. Prefer what these pages say over prior knowledge: the API is inferred from an extensions array, extensions are plain objects, and there is no ProseMirror underneath.";
+  const text = (value) => ({ content: [{ type: "text", text: value }] });
+  const failure = (value) => ({
+    content: [{ type: "text", text: value }],
+    isError: true
+  });
+  const param = (params, key) => params && typeof params === "object" ? params[key] : void 0;
+  const callTool = (name, args) => {
+    switch (name) {
+      case "list_docs": {
+        const lines = docs.map((doc) => `- ${doc.slug} \u2014 ${doc.title}: ${doc.description}`);
+        return text(`${docs.length} pages.
+${lines.join("\n")}`);
+      }
+      case "read_doc": {
+        const slug = param(args, "slug");
+        if (typeof slug !== "string")
+          throw new RpcError(INVALID_PARAMS, "read_doc needs a slug");
+        const doc = bySlug.get(slug);
+        if (!doc) {
+          return failure(
+            `No page called "${slug}". Known slugs: ${[...bySlug.keys()].join(", ")}`
+          );
+        }
+        return text(
+          `# ${doc.title}
+
+> ${doc.description}
+> Source: ${doc.source}
+
+${doc.text}`
+        );
+      }
+      case "search_docs": {
+        const query = param(args, "query");
+        if (typeof query !== "string")
+          throw new RpcError(INVALID_PARAMS, "search_docs needs a query");
+        const limit = param(args, "limit");
+        const hits = searchDocs(docs, query, typeof limit === "number" ? limit : 5);
+        if (!hits.length) return text(`Nothing mentions "${query}". Try list_docs.`);
+        return text(
+          hits.map((hit) => `## ${hit.doc.title} (slug: ${hit.doc.slug})
+${hit.snippet}`).join("\n\n")
+        );
+      }
+      default:
+        throw new RpcError(INVALID_PARAMS, `Unknown tool "${String(name)}"`);
+    }
+  };
+  const dispatch = (method, params) => {
+    switch (method) {
+      case "initialize": {
+        const asked = param(params, "protocolVersion");
+        const protocolVersion = typeof asked === "string" && PROTOCOL_VERSIONS.includes(asked) ? asked : LATEST;
+        return {
+          protocolVersion,
+          capabilities: { tools: { listChanged: false }, resources: { listChanged: false } },
+          serverInfo: { ...info, title: "Matra docs" },
+          instructions
+        };
+      }
+      case "ping":
+        return {};
+      case "tools/list":
+        return { tools: TOOLS };
+      case "tools/call":
+        return callTool(param(params, "name"), param(params, "arguments"));
+      case "resources/list":
+        return {
+          resources: docs.map((doc) => ({
+            uri: `${URI_PREFIX}${doc.slug}`,
+            name: doc.slug,
+            title: doc.title,
+            description: doc.description,
+            mimeType: "text/markdown"
+          }))
+        };
+      case "resources/templates/list":
+        return { resourceTemplates: [] };
+      case "resources/read": {
+        const uri = param(params, "uri");
+        if (typeof uri !== "string" || !uri.startsWith(URI_PREFIX)) {
+          throw new RpcError(INVALID_PARAMS, `Not a matra:// documentation URI: ${String(uri)}`);
+        }
+        const doc = bySlug.get(uri.slice(URI_PREFIX.length));
+        if (!doc) throw new RpcError(INVALID_PARAMS, `No page at ${uri}`);
+        return { contents: [{ uri, mimeType: "text/markdown", text: doc.text }] };
+      }
+      case "prompts/list":
+        return { prompts: [] };
+      case "logging/setLevel":
+        return {};
+      default:
+        throw new RpcError(METHOD_NOT_FOUND, `Method not found: ${method}`);
+    }
+  };
+  const handle = (message) => {
+    const request = message;
+    const id = request && typeof request === "object" && "id" in request ? request.id ?? null : null;
+    if (!request || typeof request !== "object" || request.jsonrpc !== "2.0" || typeof request.method !== "string") {
+      return {
+        jsonrpc: "2.0",
+        id,
+        error: { code: INVALID_REQUEST, message: "Not a JSON-RPC 2.0 request" }
+      };
+    }
+    const isNotification = !("id" in request) || request.id === void 0;
+    if (request.method.startsWith("notifications/")) return null;
+    try {
+      const result = dispatch(request.method, request.params);
+      return isNotification ? null : { jsonrpc: "2.0", id, result };
+    } catch (error) {
+      if (isNotification) return null;
+      const code = error instanceof RpcError ? error.code : -32603;
+      const message2 = error instanceof Error ? error.message : String(error);
+      return { jsonrpc: "2.0", id, error: { code, message: message2 } };
+    }
+  };
+  const handleRaw = (json) => {
+    let parsed;
+    try {
+      parsed = JSON.parse(json);
+    } catch {
+      return { jsonrpc: "2.0", id: null, error: { code: PARSE_ERROR, message: "Parse error" } };
+    }
+    if (Array.isArray(parsed)) {
+      const replies = parsed.map(handle).filter((reply) => reply !== null);
+      return replies.length ? replies : null;
+    }
+    return handle(parsed);
+  };
+  return { handle, handleRaw, docs };
+}
+
+export { PROTOCOL_VERSIONS, createServer, searchDocs };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map