@aparte/docs-mcp 0.16.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aparté
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# @aparte/docs-mcp
+
+The aparté documentation as an **MCP server**, for the coding agent that is writing your
+integration. Four tools — list the topics, search, read a page, read a whole topic — over
+the text the docs site publishes for models (`apartejs.dev/llms.txt` and its per-topic
+files), so the answer is always the docs of the version that ships.
+
+```bash
+npx @aparte/docs-mcp
+```
+
+That is the whole install for a client that spawns a command. Claude Code:
+
+```bash
+claude mcp add aparte-docs -- npx -y @aparte/docs-mcp
+```
+
+Claude Desktop / Cursor / any client with a JSON config:
+
+```json
+{ "mcpServers": { "aparte-docs": { "command": "npx", "args": ["-y", "@aparte/docs-mcp"] } } }
+```
+
+## The four tools
+
+| Tool | Ask it for |
+| --- | --- |
+| `list_sets` | The topics the docs are split into, one sentence each — start here. |
+| `search_docs` | Pages ranked for plain words (`"approve a tool call"`, `"systemPrompt false"`, `"finish a turn in display-only"`), with a snippet. |
+| `get_page` | One page's markdown, by title. |
+| `get_set` | A whole topic at once (25–250 KB): tools & approval, bring your own loop, theming & the UI kit, providers, reference. |
+
+## Why it reads the site rather than bundling it
+
+Every `@aparte/*` package ships at one version and the site deploys from the same commit,
+so "the docs online" are the docs of the version you installed — and the package stays a
+few kilobytes with nothing to go stale. It needs the network. For an offline or staging
+setup, serve a docs build yourself and point the server at it:
+
+```bash
+APARTE_DOCS_URL=http://localhost:4321 npx @aparte/docs-mcp
+```
+
+That URL is the only origin the server ever fetches from. The index it reads lists one
+URL per topic, and those are absolute production URLs even in a local build — so the
+server takes their **path** and asks `APARTE_DOCS_URL` for it. A local build is therefore
+read locally, and an index entry naming some other host is not a request your machine
+makes. Anything that does not resolve to `http`/`https` is refused.
+
+## Embedding it
+
+```ts
+import { createDocsMcpServer } from '@aparte/docs-mcp';
+
+const server = createDocsMcpServer({ baseUrl: 'https://apartejs.dev' });
+// connect it to the transport of your choice (stdio, streamable HTTP…)
+```
+
+`DocsSource`, `parseIndex`, `splitPages` and `searchPages` are exported too, for a host
+that wants the text without the protocol.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createDocsMcpServer } from "./index.js";
+const server = createDocsMcpServer({ baseUrl: process.env["APARTE_DOCS_URL"] });
+await server.connect(new StdioServerTransport());
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sources":["../src/cli.ts"],"sourcesContent":["/**\n * `npx @aparte/docs-mcp` — the server over stdio, for Claude Code, Claude Desktop, Cursor\n * and every other MCP client that spawns a command. `APARTE_DOCS_URL` points it at\n * another docs origin (a local `astro build` served on localhost, a staging site).\n */\nimport { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';\nimport { createDocsMcpServer } from './index.js';\n\nconst server = createDocsMcpServer({ baseUrl: process.env['APARTE_DOCS_URL'] });\nawait server.connect(new StdioServerTransport());\n"],"names":[],"mappings":";;;AAQA,MAAM,SAAS,oBAAoB,EAAE,SAAS,QAAQ,IAAI,iBAAiB,GAAG;AAC9E,MAAM,OAAO,QAAQ,IAAI,sBAAsB;"}

package/dist/index.d.ts

@@ -0,0 +1,130 @@
+/**
+ * @aparte/docs-mcp — the aparté documentation as an MCP server.
+ *
+ * Why it exists: two consumers' coding assistants could not FIND things the docs
+ * already had — the approval elicitation (one rebuilt a modal it already had), the
+ * UI kit of classes, `systemPrompt: false`. A model that reads a site cold misses;
+ * a model that can ask finds. This server gives it four questions to ask.
+ *
+ * Where the text comes from: the site itself. `apartejs.dev/llms.txt` is an index the
+ * docs build writes (starlight-llms-txt), listing one file per topic — tools & approval,
+ * bring your own loop, theming & the UI kit, providers, reference — and a full dump.
+ * The server fetches those on demand and caches them for the process. No snapshot is
+ * bundled: `main` is what npm serves, so "the docs online" are the docs of the version
+ * you installed, and the package stays a few kilobytes. It needs the network; point
+ * `baseUrl` at a local `astro build` output served on localhost to work offline.
+ *
+ * `baseUrl` is the only origin this server ever talks to. An index is remote text, and
+ * the URLs it lists are taken for their PATH alone — a set entry naming another host
+ * would otherwise have made the machine running the agent fetch it (a metadata service,
+ * an intranet address), and `APARTE_DOCS_URL=http://localhost:4321` would have gone on
+ * reading production, since a production index lists production URLs.
+ *
+ * Every page in those files starts with `# Title` then `> description` (the plugin's
+ * format), which is what the page splitter relies on.
+ *
+ * @packageDocumentation
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/** Where the docs live. Override for a local build (`http://localhost:4321`). */
+export declare const DEFAULT_BASE_URL = "https://apartejs.dev";
+/** One entry of `llms.txt`'s "Documentation Sets" list. */
+export interface DocsSet {
+    /** The set's label as printed in the index, e.g. "Tools, approval and asking the user". */
+    label: string;
+    /**
+     * The URL the index printed, as printed — usually absolute and on the production
+     * site. It is NOT what gets fetched: only its path is, under the configured
+     * `baseUrl`. See {@link DocsSource.pagesOf}.
+     */
+    url: string;
+    /** The one-sentence description the index gives it. */
+    description: string;
+}
+/** One page inside a set file: the `# Title` / `> description` / body triplet. */
+export interface DocsPage {
+    title: string;
+    description: string;
+    /** The page's markdown, description line excluded. */
+    body: string;
+}
+/** A search hit: the page, its score, and a window of text around the first match. */
+export interface DocsHit {
+    title: string;
+    description: string;
+    score: number;
+    snippet: string;
+    /** The set the page was found in. */
+    set: string;
+}
+/** `fetch`-shaped, so a test (or an offline host) can hand in its own. */
+export type TextFetcher = (url: string) => Promise<string>;
+export interface DocsMcpOptions {
+    /**
+     * Defaults to {@link DEFAULT_BASE_URL} when unset, empty or blank. A trailing slash
+     * is tolerated. This is the only origin the server fetches from: a set the index
+     * lists contributes its path, never its host.
+     */
+    baseUrl?: string;
+    /** Defaults to global `fetch` + `response.text()`; a non-2xx status throws. */
+    fetchText?: TextFetcher;
+}
+/**
+ * Parse the "Documentation Sets" list of an `llms.txt`: `- [label](url): description`.
+ * The two entries the plugin always writes (abridged / complete) are kept — a caller
+ * may want the full dump — and everything else in the file is ignored.
+ */
+export declare function parseIndex(text: string): DocsSet[];
+/**
+ * Split a set file into pages. A page starts with a line `# Title`; the plugin writes
+ * the page's description as a `> …` quote right under it. The `<SYSTEM>…</SYSTEM>`
+ * preamble of a custom set is dropped.
+ */
+export declare function splitPages(text: string): DocsPage[];
+/**
+ * The searchable terms of a query: lower-cased words, stopwords and one-letter words
+ * dropped (`"approve a tool call"` once matched every page on its "a"), and long words
+ * shortened to a stem so "approve" finds "approval" and "streaming" finds "stream":
+ * six letters or more lose their last two.
+ */
+export declare function queryTerms(query: string): string[];
+/**
+ * Rank pages for a query: every query term counted in the body, weighted ×5 in the
+ * title and ×3 in the description; a page missing every term scores 0 and is dropped.
+ * Plain term frequency is enough for ~60 pages — a model refines with `get_page`.
+ */
+export declare function searchPages(pages: DocsPage[], query: string, set?: string): DocsHit[];
+/** The loaded-and-cached view of the site: the index, and each set's pages on demand. */
+export declare class DocsSource {
+    private readonly base;
+    private readonly fetchText;
+    private index;
+    private readonly pages;
+    constructor(options?: DocsMcpOptions);
+    /** The sets listed by `llms.txt`, fetched once. */
+    sets(): Promise<DocsSet[]>;
+    /** A set by label (case-insensitive, substring tolerated), or undefined. */
+    findSet(label: string): Promise<DocsSet | undefined>;
+    /**
+     * The URL to actually fetch for something the index named: its path (and query),
+     * under `baseUrl`. The host the index printed is discarded — an index is text from
+     * the network, and following it verbatim is a request made from the machine running
+     * the agent. It is also what made `APARTE_DOCS_URL` a half-measure: a local build
+     * serves the production index, whose entries are absolute production URLs, so
+     * pointing the server at localhost still read the live site.
+     *
+     * Anything that does not resolve to http(s) — `file:`, `data:`, a bare scheme — is
+     * refused rather than quietly re-based, because it is not a docs URL at all.
+     */
+    private resolve;
+    /** The pages of one set, fetched once per set — from `baseUrl`, whatever host the index named. */
+    pagesOf(set: DocsSet): Promise<DocsPage[]>;
+    /** The sets to search: the one named, or every topic set (not the two dumps). */
+    scope(setLabel?: string): Promise<DocsSet[]>;
+}
+/**
+ * Build the MCP server. Four tools, in the order a model uses them:
+ * `list_sets` → `search_docs` → `get_page`, and `get_set` for a whole topic at once.
+ */
+export declare function createDocsMcpServer(options?: DocsMcpOptions): McpServer;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAgBpE,iFAAiF;AACjF,eAAO,MAAM,gBAAgB,yBAAyB,CAAC;AAEvD,2DAA2D;AAC3D,MAAM,WAAW,OAAO;IACpB,2FAA2F;IAC3F,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;CACvB;AAED,kFAAkF;AAClF,MAAM,WAAW,QAAQ;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,sFAAsF;AACtF,MAAM,WAAW,OAAO;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAC;CACf;AAED,0EAA0E;AAC1E,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE3D,MAAM,WAAW,cAAc;IAC3B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,WAAW,CAAC;CAC3B;AAQD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAUlD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,EAAE,CAmBnD;AAKD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAMlD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,SAAK,GAAG,OAAO,EAAE,CA0BjF;AAED,yFAAyF;AACzF,qBAAa,UAAU;IACnB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,KAAK,CAAmC;IAChD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0C;gBAEpD,OAAO,GAAE,cAAmB;IAOxC,mDAAmD;IACnD,IAAI,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAK1B,4EAA4E;IACtE,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;IAO1D;;;;;;;;;;OAUG;IACH,OAAO,CAAC,OAAO;IAWf,kGAAkG;IAClG,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAQ1C,iFAAiF;IAC3E,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CAcrD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,cAAmB,GAAG,SAAS,CA8D3E"}

package/dist/index.js

@@ -0,0 +1,227 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { createRequire } from "node:module";
+const pkgVersion = (() => {
+  try {
+    return createRequire(import.meta.url)("../package.json").version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+})();
+const DEFAULT_BASE_URL = "https://apartejs.dev";
+const defaultFetchText = async (url) => {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`${url} answered ${res.status}`);
+  return res.text();
+};
+function parseIndex(text) {
+  const sets = [];
+  let inSets = false;
+  for (const line of text.split("\n")) {
+    if (/^## /.test(line)) {
+      inSets = /^## Documentation Sets/.test(line);
+      continue;
+    }
+    if (!inSets) continue;
+    const m = /^- \[([^\]]+)\]\(([^)]+)\)(?::\s*(.*))?$/.exec(line.trim());
+    if (m) sets.push({ label: m[1], url: m[2], description: (m[3] ?? "").trim() });
+  }
+  return sets;
+}
+function splitPages(text) {
+  const pages = [];
+  let current = null;
+  for (const raw of text.replace(/^<SYSTEM>[\s\S]*?<\/SYSTEM>\s*/u, "").split("\n")) {
+    const title = /^# (.+)$/.exec(raw);
+    if (title) {
+      if (current) pages.push(current);
+      current = { title: title[1].trim(), description: "", body: "" };
+      continue;
+    }
+    if (!current) continue;
+    if (!current.description && !current.body.trim() && /^> /.test(raw)) {
+      current.description = raw.slice(2).trim();
+      continue;
+    }
+    current.body += raw + "\n";
+  }
+  if (current) pages.push(current);
+  return pages.map((p) => ({ ...p, body: p.body.trim() }));
+}
+const STOPWORDS = /* @__PURE__ */ new Set(["a", "an", "the", "to", "in", "on", "of", "and", "or", "is", "it", "my", "your", "how", "do", "i", "with", "for", "from", "be", "can"]);
+function queryTerms(query) {
+  const words = query.toLowerCase().match(/[a-z0-9_@./-]+/g) ?? [];
+  const terms = words.filter((w) => w.length > 1 && !STOPWORDS.has(w)).map((w) => w.length >= 6 ? w.slice(0, -2) : w);
+  return [...new Set(terms)];
+}
+function searchPages(pages, query, set = "") {
+  const terms = queryTerms(query);
+  if (!terms.length) return [];
+  const hits = [];
+  for (const page of pages) {
+    const title = page.title.toLowerCase();
+    const desc = page.description.toLowerCase();
+    const body = page.body.toLowerCase();
+    let score = 0;
+    let first = -1;
+    for (const term of terms) {
+      if (title.includes(term)) score += 5;
+      if (desc.includes(term)) score += 3;
+      let at = body.indexOf(term);
+      while (at !== -1) {
+        score += 1;
+        if (first === -1 || at < first) first = at;
+        at = body.indexOf(term, at + term.length);
+      }
+    }
+    if (!score) continue;
+    const start = Math.max(0, first === -1 ? 0 : first - 160);
+    const snippet = page.body.slice(start, start + 400).replace(/\s+/g, " ").trim();
+    hits.push({ title: page.title, description: page.description, score, snippet, set });
+  }
+  return hits.sort((a, b) => b.score - a.score);
+}
+class DocsSource {
+  base;
+  fetchText;
+  index = null;
+  pages = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    this.base = (options.baseUrl?.trim() || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.fetchText = options.fetchText ?? defaultFetchText;
+  }
+  /** The sets listed by `llms.txt`, fetched once. */
+  sets() {
+    this.index ??= this.fetchText(`${this.base}/llms.txt`).then(parseIndex);
+    return this.index;
+  }
+  /** A set by label (case-insensitive, substring tolerated), or undefined. */
+  async findSet(label) {
+    const wanted = label.trim().toLowerCase();
+    const sets = await this.sets();
+    return sets.find((s) => s.label.toLowerCase() === wanted) ?? sets.find((s) => s.label.toLowerCase().includes(wanted));
+  }
+  /**
+   * The URL to actually fetch for something the index named: its path (and query),
+   * under `baseUrl`. The host the index printed is discarded — an index is text from
+   * the network, and following it verbatim is a request made from the machine running
+   * the agent. It is also what made `APARTE_DOCS_URL` a half-measure: a local build
+   * serves the production index, whose entries are absolute production URLs, so
+   * pointing the server at localhost still read the live site.
+   *
+   * Anything that does not resolve to http(s) — `file:`, `data:`, a bare scheme — is
+   * refused rather than quietly re-based, because it is not a docs URL at all.
+   */
+  resolve(url) {
+    const parsed = new URL(url, `${new URL(this.base).origin}/`);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      throw new Error(`Refusing to fetch "${url}": ${parsed.protocol} is not a documentation URL`);
+    }
+    return `${this.base}${parsed.pathname}${parsed.search}`;
+  }
+  /** The pages of one set, fetched once per set — from `baseUrl`, whatever host the index named. */
+  pagesOf(set) {
+    let url;
+    try {
+      url = this.resolve(set.url);
+    } catch (error) {
+      return Promise.reject(error);
+    }
+    let p = this.pages.get(url);
+    if (!p) {
+      p = this.fetchText(url).then(splitPages);
+      this.pages.set(url, p);
+    }
+    return p;
+  }
+  /** The sets to search: the one named, or every topic set (not the two dumps). */
+  async scope(setLabel) {
+    if (setLabel) {
+      const one = await this.findSet(setLabel);
+      return one ? [one] : [];
+    }
+    const sets = await this.sets();
+    const topics = sets.filter((s) => !/^(Abridged|Complete) documentation$/.test(s.label));
+    if (topics.length) return topics;
+    const full = sets.find((s) => /^Complete documentation$/.test(s.label));
+    return full ? [full] : sets.slice(0, 1);
+  }
+}
+function createDocsMcpServer(options = {}) {
+  const source = new DocsSource(options);
+  const server = new McpServer({ name: "aparte-docs", version: pkgVersion });
+  const text = (t) => ({ content: [{ type: "text", text: t }] });
+  server.registerTool("list_sets", {
+    title: "List the documentation sets",
+    description: "The topics the aparté docs are split into (tools & approval, bring your own loop, theming & the UI kit, providers, reference…), each with a one-sentence description. Start here.",
+    inputSchema: {}
+  }, async () => {
+    const sets = await source.sets();
+    return text(sets.map((s) => `- ${s.label}: ${s.description}`).join("\n"));
+  });
+  server.registerTool("get_set", {
+    title: "Read a whole set",
+    description: "The full text of one documentation set (every page of that topic, markdown). Use when one topic is all you need; a set is 25–250 KB.",
+    inputSchema: { set: z.string().describe('A set label from list_sets, or a distinctive part of it, e.g. "approval" or "theming".') }
+  }, async ({ set }) => {
+    const found = await source.findSet(set);
+    if (!found) return text(`No set matches "${set}". Sets: ${(await source.sets()).map((s) => s.label).join(" · ")}`);
+    const pages = await source.pagesOf(found);
+    return text(pages.map((p) => `# ${p.title}
+
+> ${p.description}
+
+${p.body}`).join("\n\n"));
+  });
+  server.registerTool("search_docs", {
+    title: "Search the docs",
+    description: 'Rank the documentation pages for a query (plain words: "approve a tool call", "systemPrompt false", "finish a turn in display-only"). Returns titles, descriptions and a snippet; read a hit with get_page.',
+    inputSchema: {
+      query: z.string().describe("What you are looking for, in plain words."),
+      set: z.string().optional().describe("Restrict to one set (label or part of it). Default: every topic set."),
+      limit: z.number().int().min(1).max(20).optional().describe("How many hits. Default 8.")
+    }
+  }, async ({ query, set, limit }) => {
+    const scope = await source.scope(set);
+    if (!scope.length) return text(`No set matches "${set}".`);
+    const hits = [];
+    for (const s of scope) hits.push(...searchPages(await source.pagesOf(s), query, s.label));
+    const seen = /* @__PURE__ */ new Set();
+    const top = hits.sort((a, b) => b.score - a.score).filter((h) => !seen.has(h.title) && seen.add(h.title)).slice(0, limit ?? 8);
+    if (!top.length) return text(`Nothing matches "${query}". Try other words, or list_sets to see the topics.`);
+    return text(top.map((h) => `## ${h.title} (score ${h.score}, set: ${h.set})
+${h.description}
+…${h.snippet}…`).join("\n\n"));
+  });
+  server.registerTool("get_page", {
+    title: "Read a page",
+    description: "The full markdown of one documentation page, by its title (as returned by search_docs; a distinctive part of the title is enough).",
+    inputSchema: {
+      title: z.string().describe("The page title, or a distinctive part of it."),
+      set: z.string().optional().describe("The set to look in, if known — faster.")
+    }
+  }, async ({ title, set }) => {
+    const wanted = title.trim().toLowerCase();
+    for (const s of await source.scope(set)) {
+      const pages = await source.pagesOf(s);
+      const page = pages.find((p) => p.title.toLowerCase() === wanted) ?? pages.find((p) => p.title.toLowerCase().includes(wanted));
+      if (page) return text(`# ${page.title}
+
+> ${page.description}
+
+${page.body}`);
+    }
+    return text(`No page titled "${title}". search_docs finds titles.`);
+  });
+  return server;
+}
+export {
+  DEFAULT_BASE_URL,
+  DocsSource,
+  createDocsMcpServer,
+  parseIndex,
+  queryTerms,
+  searchPages,
+  splitPages
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/index.ts"],"sourcesContent":["/**\n * @aparte/docs-mcp — the aparté documentation as an MCP server.\n *\n * Why it exists: two consumers' coding assistants could not FIND things the docs\n * already had — the approval elicitation (one rebuilt a modal it already had), the\n * UI kit of classes, `systemPrompt: false`. A model that reads a site cold misses;\n * a model that can ask finds. This server gives it four questions to ask.\n *\n * Where the text comes from: the site itself. `apartejs.dev/llms.txt` is an index the\n * docs build writes (starlight-llms-txt), listing one file per topic — tools & approval,\n * bring your own loop, theming & the UI kit, providers, reference — and a full dump.\n * The server fetches those on demand and caches them for the process. No snapshot is\n * bundled: `main` is what npm serves, so \"the docs online\" are the docs of the version\n * you installed, and the package stays a few kilobytes. It needs the network; point\n * `baseUrl` at a local `astro build` output served on localhost to work offline.\n *\n * `baseUrl` is the only origin this server ever talks to. An index is remote text, and\n * the URLs it lists are taken for their PATH alone — a set entry naming another host\n * would otherwise have made the machine running the agent fetch it (a metadata service,\n * an intranet address), and `APARTE_DOCS_URL=http://localhost:4321` would have gone on\n * reading production, since a production index lists production URLs.\n *\n * Every page in those files starts with `# Title` then `> description` (the plugin's\n * format), which is what the page splitter relies on.\n *\n * @packageDocumentation\n */\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { z } from 'zod';\nimport { createRequire } from 'node:module';\n\n// The version the MCP handshake reports is the PUBLISHED one: changesets bumps\n// package.json and nothing else, so a literal here went stale at every release.\n// `../package.json` resolves to this package's manifest from dist/index.js, from\n// src/index.ts under the workspace source condition, and under vitest alike.\nconst pkgVersion = (() => {\n    try {\n        return (createRequire(import.meta.url)('../package.json') as { version?: string }).version ?? '0.0.0';\n    } catch {\n        return '0.0.0';\n    }\n})();\n\n/** Where the docs live. Override for a local build (`http://localhost:4321`). */\nexport const DEFAULT_BASE_URL = 'https://apartejs.dev';\n\n/** One entry of `llms.txt`'s \"Documentation Sets\" list. */\nexport interface DocsSet {\n    /** The set's label as printed in the index, e.g. \"Tools, approval and asking the user\". */\n    label: string;\n    /**\n     * The URL the index printed, as printed — usually absolute and on the production\n     * site. It is NOT what gets fetched: only its path is, under the configured\n     * `baseUrl`. See {@link DocsSource.pagesOf}.\n     */\n    url: string;\n    /** The one-sentence description the index gives it. */\n    description: string;\n}\n\n/** One page inside a set file: the `# Title` / `> description` / body triplet. */\nexport interface DocsPage {\n    title: string;\n    description: string;\n    /** The page's markdown, description line excluded. */\n    body: string;\n}\n\n/** A search hit: the page, its score, and a window of text around the first match. */\nexport interface DocsHit {\n    title: string;\n    description: string;\n    score: number;\n    snippet: string;\n    /** The set the page was found in. */\n    set: string;\n}\n\n/** `fetch`-shaped, so a test (or an offline host) can hand in its own. */\nexport type TextFetcher = (url: string) => Promise<string>;\n\nexport interface DocsMcpOptions {\n    /**\n     * Defaults to {@link DEFAULT_BASE_URL} when unset, empty or blank. A trailing slash\n     * is tolerated. This is the only origin the server fetches from: a set the index\n     * lists contributes its path, never its host.\n     */\n    baseUrl?: string;\n    /** Defaults to global `fetch` + `response.text()`; a non-2xx status throws. */\n    fetchText?: TextFetcher;\n}\n\nconst defaultFetchText: TextFetcher = async (url) => {\n    const res = await fetch(url);\n    if (!res.ok) throw new Error(`${url} answered ${res.status}`);\n    return res.text();\n};\n\n/**\n * Parse the \"Documentation Sets\" list of an `llms.txt`: `- [label](url): description`.\n * The two entries the plugin always writes (abridged / complete) are kept — a caller\n * may want the full dump — and everything else in the file is ignored.\n */\nexport function parseIndex(text: string): DocsSet[] {\n    const sets: DocsSet[] = [];\n    let inSets = false;\n    for (const line of text.split('\\n')) {\n        if (/^## /.test(line)) { inSets = /^## Documentation Sets/.test(line); continue; }\n        if (!inSets) continue;\n        const m = /^- \\[([^\\]]+)\\]\\(([^)]+)\\)(?::\\s*(.*))?$/.exec(line.trim());\n        if (m) sets.push({ label: m[1]!, url: m[2]!, description: (m[3] ?? '').trim() });\n    }\n    return sets;\n}\n\n/**\n * Split a set file into pages. A page starts with a line `# Title`; the plugin writes\n * the page's description as a `> …` quote right under it. The `<SYSTEM>…</SYSTEM>`\n * preamble of a custom set is dropped.\n */\nexport function splitPages(text: string): DocsPage[] {\n    const pages: DocsPage[] = [];\n    let current: DocsPage | null = null;\n    for (const raw of text.replace(/^<SYSTEM>[\\s\\S]*?<\\/SYSTEM>\\s*/u, '').split('\\n')) {\n        const title = /^# (.+)$/.exec(raw);\n        if (title) {\n            if (current) pages.push(current);\n            current = { title: title[1]!.trim(), description: '', body: '' };\n            continue;\n        }\n        if (!current) continue;\n        if (!current.description && !current.body.trim() && /^> /.test(raw)) {\n            current.description = raw.slice(2).trim();\n            continue;\n        }\n        current.body += raw + '\\n';\n    }\n    if (current) pages.push(current);\n    return pages.map((p) => ({ ...p, body: p.body.trim() }));\n}\n\n/** Words a model puts in a question and no page is about. */\nconst STOPWORDS = new Set(['a', 'an', 'the', 'to', 'in', 'on', 'of', 'and', 'or', 'is', 'it', 'my', 'your', 'how', 'do', 'i', 'with', 'for', 'from', 'be', 'can']);\n\n/**\n * The searchable terms of a query: lower-cased words, stopwords and one-letter words\n * dropped (`\"approve a tool call\"` once matched every page on its \"a\"), and long words\n * shortened to a stem so \"approve\" finds \"approval\" and \"streaming\" finds \"stream\":\n * six letters or more lose their last two.\n */\nexport function queryTerms(query: string): string[] {\n    const words = query.toLowerCase().match(/[a-z0-9_@./-]+/g) ?? [];\n    const terms = words\n        .filter((w) => w.length > 1 && !STOPWORDS.has(w))\n        .map((w) => (w.length >= 6 ? w.slice(0, -2) : w));\n    return [...new Set(terms)];\n}\n\n/**\n * Rank pages for a query: every query term counted in the body, weighted ×5 in the\n * title and ×3 in the description; a page missing every term scores 0 and is dropped.\n * Plain term frequency is enough for ~60 pages — a model refines with `get_page`.\n */\nexport function searchPages(pages: DocsPage[], query: string, set = ''): DocsHit[] {\n    const terms = queryTerms(query);\n    if (!terms.length) return [];\n    const hits: DocsHit[] = [];\n    for (const page of pages) {\n        const title = page.title.toLowerCase();\n        const desc = page.description.toLowerCase();\n        const body = page.body.toLowerCase();\n        let score = 0;\n        let first = -1;\n        for (const term of terms) {\n            if (title.includes(term)) score += 5;\n            if (desc.includes(term)) score += 3;\n            let at = body.indexOf(term);\n            while (at !== -1) {\n                score += 1;\n                if (first === -1 || at < first) first = at;\n                at = body.indexOf(term, at + term.length);\n            }\n        }\n        if (!score) continue;\n        const start = Math.max(0, first === -1 ? 0 : first - 160);\n        const snippet = page.body.slice(start, start + 400).replace(/\\s+/g, ' ').trim();\n        hits.push({ title: page.title, description: page.description, score, snippet, set });\n    }\n    return hits.sort((a, b) => b.score - a.score);\n}\n\n/** The loaded-and-cached view of the site: the index, and each set's pages on demand. */\nexport class DocsSource {\n    private readonly base: string;\n    private readonly fetchText: TextFetcher;\n    private index: Promise<DocsSet[]> | null = null;\n    private readonly pages = new Map<string, Promise<DocsPage[]>>();\n\n    constructor(options: DocsMcpOptions = {}) {\n        // `||`, not `??`: an env var exported but empty (`APARTE_DOCS_URL=\"\"`) is\n        // \"unset\", and a pasted value with a stray newline fails the same way.\n        this.base = (options.baseUrl?.trim() || DEFAULT_BASE_URL).replace(/\\/+$/, '');\n        this.fetchText = options.fetchText ?? defaultFetchText;\n    }\n\n    /** The sets listed by `llms.txt`, fetched once. */\n    sets(): Promise<DocsSet[]> {\n        this.index ??= this.fetchText(`${this.base}/llms.txt`).then(parseIndex);\n        return this.index;\n    }\n\n    /** A set by label (case-insensitive, substring tolerated), or undefined. */\n    async findSet(label: string): Promise<DocsSet | undefined> {\n        const wanted = label.trim().toLowerCase();\n        const sets = await this.sets();\n        return sets.find((s) => s.label.toLowerCase() === wanted)\n            ?? sets.find((s) => s.label.toLowerCase().includes(wanted));\n    }\n\n    /**\n     * The URL to actually fetch for something the index named: its path (and query),\n     * under `baseUrl`. The host the index printed is discarded — an index is text from\n     * the network, and following it verbatim is a request made from the machine running\n     * the agent. It is also what made `APARTE_DOCS_URL` a half-measure: a local build\n     * serves the production index, whose entries are absolute production URLs, so\n     * pointing the server at localhost still read the live site.\n     *\n     * Anything that does not resolve to http(s) — `file:`, `data:`, a bare scheme — is\n     * refused rather than quietly re-based, because it is not a docs URL at all.\n     */\n    private resolve(url: string): string {\n        // Against the ORIGIN, not against `base`: a path the index gives is a path from\n        // the docs root, so a `baseUrl` that carries a prefix (`https://host/docs`) must\n        // prepend it once, not resolve under it and then prepend it again.\n        const parsed = new URL(url, `${new URL(this.base).origin}/`);\n        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {\n            throw new Error(`Refusing to fetch \"${url}\": ${parsed.protocol} is not a documentation URL`);\n        }\n        return `${this.base}${parsed.pathname}${parsed.search}`;\n    }\n\n    /** The pages of one set, fetched once per set — from `baseUrl`, whatever host the index named. */\n    pagesOf(set: DocsSet): Promise<DocsPage[]> {\n        let url: string;\n        try { url = this.resolve(set.url); } catch (error) { return Promise.reject(error as Error); }\n        let p = this.pages.get(url);\n        if (!p) { p = this.fetchText(url).then(splitPages); this.pages.set(url, p); }\n        return p;\n    }\n\n    /** The sets to search: the one named, or every topic set (not the two dumps). */\n    async scope(setLabel?: string): Promise<DocsSet[]> {\n        if (setLabel) {\n            const one = await this.findSet(setLabel);\n            return one ? [one] : [];\n        }\n        const sets = await this.sets();\n        const topics = sets.filter((s) => !/^(Abridged|Complete) documentation$/.test(s.label));\n        if (topics.length) return topics;\n        // An index with no topic sets (an older site, a bare starlight-llms-txt): search\n        // the complete dump alone — both dumps hold the same pages, twice the fetch and\n        // every hit doubled.\n        const full = sets.find((s) => /^Complete documentation$/.test(s.label));\n        return full ? [full] : sets.slice(0, 1);\n    }\n}\n\n/**\n * Build the MCP server. Four tools, in the order a model uses them:\n * `list_sets` → `search_docs` → `get_page`, and `get_set` for a whole topic at once.\n */\nexport function createDocsMcpServer(options: DocsMcpOptions = {}): McpServer {\n    const source = new DocsSource(options);\n    const server = new McpServer({ name: 'aparte-docs', version: pkgVersion });\n    const text = (t: string) => ({ content: [{ type: 'text' as const, text: t }] });\n\n    server.registerTool('list_sets', {\n        title: 'List the documentation sets',\n        description: 'The topics the aparté docs are split into (tools & approval, bring your own loop, theming & the UI kit, providers, reference…), each with a one-sentence description. Start here.',\n        inputSchema: {},\n    }, async () => {\n        const sets = await source.sets();\n        return text(sets.map((s) => `- ${s.label}: ${s.description}`).join('\\n'));\n    });\n\n    server.registerTool('get_set', {\n        title: 'Read a whole set',\n        description: 'The full text of one documentation set (every page of that topic, markdown). Use when one topic is all you need; a set is 25–250 KB.',\n        inputSchema: { set: z.string().describe('A set label from list_sets, or a distinctive part of it, e.g. \"approval\" or \"theming\".') },\n    }, async ({ set }) => {\n        const found = await source.findSet(set);\n        if (!found) return text(`No set matches \"${set}\". Sets: ${(await source.sets()).map((s) => s.label).join(' · ')}`);\n        const pages = await source.pagesOf(found);\n        return text(pages.map((p) => `# ${p.title}\\n\\n> ${p.description}\\n\\n${p.body}`).join('\\n\\n'));\n    });\n\n    server.registerTool('search_docs', {\n        title: 'Search the docs',\n        description: 'Rank the documentation pages for a query (plain words: \"approve a tool call\", \"systemPrompt false\", \"finish a turn in display-only\"). Returns titles, descriptions and a snippet; read a hit with get_page.',\n        inputSchema: {\n            query: z.string().describe('What you are looking for, in plain words.'),\n            set: z.string().optional().describe('Restrict to one set (label or part of it). Default: every topic set.'),\n            limit: z.number().int().min(1).max(20).optional().describe('How many hits. Default 8.'),\n        },\n    }, async ({ query, set, limit }) => {\n        const scope = await source.scope(set);\n        if (!scope.length) return text(`No set matches \"${set}\".`);\n        const hits: DocsHit[] = [];\n        for (const s of scope) hits.push(...searchPages(await source.pagesOf(s), query, s.label));\n        const seen = new Set<string>();\n        const top = hits.sort((a, b) => b.score - a.score).filter((h) => !seen.has(h.title) && seen.add(h.title)).slice(0, limit ?? 8);\n        if (!top.length) return text(`Nothing matches \"${query}\". Try other words, or list_sets to see the topics.`);\n        return text(top.map((h) => `## ${h.title} (score ${h.score}, set: ${h.set})\\n${h.description}\\n…${h.snippet}…`).join('\\n\\n'));\n    });\n\n    server.registerTool('get_page', {\n        title: 'Read a page',\n        description: 'The full markdown of one documentation page, by its title (as returned by search_docs; a distinctive part of the title is enough).',\n        inputSchema: {\n            title: z.string().describe('The page title, or a distinctive part of it.'),\n            set: z.string().optional().describe('The set to look in, if known — faster.'),\n        },\n    }, async ({ title, set }) => {\n        const wanted = title.trim().toLowerCase();\n        for (const s of await source.scope(set)) {\n            const pages = await source.pagesOf(s);\n            const page = pages.find((p) => p.title.toLowerCase() === wanted) ?? pages.find((p) => p.title.toLowerCase().includes(wanted));\n            if (page) return text(`# ${page.title}\\n\\n> ${page.description}\\n\\n${page.body}`);\n        }\n        return text(`No page titled \"${title}\". search_docs finds titles.`);\n    });\n\n    return server;\n}\n"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@aparte/docs-mcp",
+  "version": "0.16.0",
+  "description": "The aparté documentation as an MCP server — a coding agent searches the guides, reads a page or a whole topic (tools & approval, bring your own loop, theming & the UI kit…), always the version that ships, straight from apartejs.dev.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "aparte-docs-mcp": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "@aparte-workspace/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "20.11.0",
+    "typescript": "^5.4.0",
+    "vite": "^6.0.0"
+  },
+  "keywords": [
+    "aparte",
+    "mcp",
+    "model-context-protocol",
+    "documentation",
+    "llms-txt",
+    "ai",
+    "chat"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/apartejs/aparte.git",
+    "directory": "packages/tools/docs-mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/apartejs/aparte/issues"
+  },
+  "scripts": {
+    "build": "vite build && tsc -b --emitDeclarationOnly --force",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  }
+}