@newtui/mcp 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the
+      purposes of this License, Derivative Works shall not include works
+      that remain separable from, or merely link (or bind by name) to the
+      interfaces of, the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing
+      the origin of the Work and reproducing the content of the NOTICE
+      file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 wolfstar-project
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,61 @@
-# Temporary Holding Version
+# @newtui/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An [MCP](https://modelcontextprotocol.io) server for the [newt/ui](https://newtui.dev) documentation — Discord-inspired components for React, Vue and plain HTML/CSS. It gives your editor's agent the docs themselves: installation per framework, theming, the token reference, accessibility notes and the registry format, read from the site rather than recalled from memory.
+
+It is the companion to `newtui mcp`, the server inside the CLI: that one answers _which components exist and what their source is_; this one answers _what the documentation says_. Run both.
+
+```bash
+npx @newtui/mcp
+```
+
+## Tools
+
+Every tool is read-only.
+
+| Tool          | What it returns                                                                                                                                    |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `list_docs`   | Every page with its title, route, description and section. `section` filters to one heading of the index, e.g. `Installation`.                     |
+| `search_docs` | Pages ranked by where every keyword appears — title, route, description, section. `content: true` searches page bodies too and adds an excerpt.    |
+| `get_doc`     | One page as Markdown. Takes a route (`/docs/theming`), a slug (`button`, `installation/nuxt`) or a full URL; an unknown page answers with matches. |
+
+## Configure your client
+
+```json
+{
+  "mcpServers": {
+    "newtui-docs": {
+      "command": "npx",
+      "args": ["-y", "@newtui/mcp@latest"]
+    }
+  }
+}
+```
+
+That shape works for Claude Code (`.mcp.json`), Cursor (`.cursor/mcp.json`) and most other clients. Claude Code can also add it in one line:
+
+```bash
+claude mcp add newtui-docs -- npx -y @newtui/mcp@latest
+```
+
+## Pointing it at another site
+
+The site resolves as `--url` > `NEWTUI_DOCS_URL` > `https://newtui.dev`:
+
+```bash
+npx @newtui/mcp --url http://localhost:4321
+NEWTUI_DOCS_URL=http://localhost:4321 npx @newtui/mcp
+```
+
+The server reads what the site publishes for agents: `llms.txt` for the page index, `llms-full.txt` for full-text search, and the `.md` twin of every page. The Blume dev server serves the twins but not the two `llms` files, so against `localhost:4321` the index comes from the JSON docs API (`/api/docs/pages.json`) and `search_docs` falls back to titles and descriptions — the answer says so in `searchedContent`. A built site (`pnpm --filter docs build`, then any static server on `apps/docs/dist`) has everything.
+
+Responses are cached in memory for five minutes; a 404 is cached too, a server error is not.
+
+## Development
+
+```bash
+pnpm build       # tsdown -> dist/index.js
+pnpm typecheck   # tsc --noEmit
+pnpm test        # vitest, with the network replaced by an in-memory site
+```
+
+newt/ui is an independent, community-built project. It is visually inspired by Discord's client but is not affiliated with, endorsed by, or sponsored by Discord Inc.

package/dist/index.js

@@ -0,0 +1,490 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// package.json
+var version = "0.1.1";
+
+// \0@oxc-project+runtime@0.157.0/helpers/esm/typeof.js
+function _typeof(o) {
+	"@babel/helpers - typeof";
+	return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function(o) {
+		return typeof o;
+	} : function(o) {
+		return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o;
+	}, _typeof(o);
+}
+
+// \0@oxc-project+runtime@0.157.0/helpers/esm/toPrimitive.js
+function toPrimitive(t, e) {
+	if ("object" != _typeof(t) || !t) return t;
+	var r;
+	if ("undefined" != typeof Symbol && void 0 !== (r = t[Symbol.toPrimitive])) {
+		var i = r.call(t, e || "default");
+		if ("object" != _typeof(i)) return i;
+		throw new TypeError("@@toPrimitive must return a primitive value.");
+	}
+	return ("string" === e ? String : Number)(t);
+}
+
+// \0@oxc-project+runtime@0.157.0/helpers/esm/toPropertyKey.js
+function toPropertyKey(t) {
+	var i = toPrimitive(t, "string");
+	return "symbol" == _typeof(i) ? i : i + "";
+}
+
+// \0@oxc-project+runtime@0.157.0/helpers/esm/defineProperty.js
+function _defineProperty(e, r, t) {
+	return (r = toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
+		value: t,
+		enumerable: !0,
+		configurable: !0,
+		writable: !0
+	}) : e[r] = t, e;
+}
+
+// \0@oxc-project+runtime@0.157.0/helpers/esm/checkPrivateRedeclaration.js
+function _checkPrivateRedeclaration(e, t) {
+	if (t.has(e)) throw new TypeError("Cannot initialize the same private elements twice on an object");
+}
+
+// \0@oxc-project+runtime@0.157.0/helpers/esm/classPrivateMethodInitSpec.js
+function _classPrivateMethodInitSpec(e, a) {
+	_checkPrivateRedeclaration(e, a), a.add(e);
+}
+
+// \0@oxc-project+runtime@0.157.0/helpers/esm/classPrivateFieldInitSpec.js
+function _classPrivateFieldInitSpec(e, t, a) {
+	_checkPrivateRedeclaration(e, t), t.set(e, a);
+}
+
+// \0@oxc-project+runtime@0.157.0/helpers/esm/assertClassBrand.js
+function _assertClassBrand(e, t, n) {
+	if ("function" == typeof e ? e === t : e.has(t)) return arguments.length < 3 ? t : n;
+	throw new TypeError("Private element is not present on this object");
+}
+
+// \0@oxc-project+runtime@0.157.0/helpers/esm/classPrivateFieldSet2.js
+function _classPrivateFieldSet2(s, a, r) {
+	return s.set(_assertClassBrand(s, a), r), r;
+}
+
+// \0@oxc-project+runtime@0.157.0/helpers/esm/classPrivateFieldGet2.js
+function _classPrivateFieldGet2(s, a) {
+	return s.get(_assertClassBrand(s, a));
+}
+
+// src/docs.ts
+const DEFAULT_DOCS_URL = "https://newtui.dev";
+/** How long a fetched document stays fresh, in milliseconds. */
+const DEFAULT_CACHE_TTL = 3e5;
+var DocsRequestError = class extends Error {
+	constructor(url, status) {
+		super(`GET ${url} answered ${status}`);
+		_defineProperty(this, "url", void 0);
+		_defineProperty(this, "status", void 0);
+		this.name = "DocsRequestError";
+		this.url = url;
+		this.status = status;
+	}
+};
+/** The subset of Blume's JSON docs API the fallback index reads. */
+const pagesApiSchema = z.object({ pages: z.array(z.object({
+	route: z.string(),
+	title: z.string(),
+	description: z.string().optional(),
+	contentType: z.string().optional()
+})) });
+/** The docs site resolves as `--url` > `NEWTUI_DOCS_URL` > the default. */
+function resolveDocsUrl(flag, env) {
+	return [flag, env].find((value) => value !== void 0 && value.trim() !== "")?.trim() ?? "https://newtui.dev";
+}
+/** Strip the trailing slash so `${base}${path}` never doubles one. */
+function normaliseBaseUrl(url) {
+	return new URL(url).toString().replace(/\/+$/u, "");
+}
+const DEFAULT_HOST = new URL(DEFAULT_DOCS_URL).host;
+function pagePathOf(href, base) {
+	const link = new URL(href, base);
+	if (link.host !== base.host && link.host !== DEFAULT_HOST) return null;
+	const path = link.pathname.replace(/\/+$/u, "") || "/";
+	const segments = path.split("/");
+	const last = segments.at(-1) ?? "";
+	if (segments.some((segment) => segment.startsWith(".")) || last.includes(".")) return null;
+	return path;
+}
+const LINK_LINE = /^- \[(?<title>[^\]]+)\]\((?<href>[^)\s]+)\)(?::\s*(?<description>.*))?$/u;
+/** Parse an `llms.txt` page index into entries rebased on `baseUrl`. */
+function parseLlmsTxt(source, baseUrl) {
+	const base = new URL(baseUrl);
+	const entries = [];
+	const seen = /* @__PURE__ */ new Set();
+	let section;
+	for (const line of source.split("\n")) {
+		if (line.startsWith("## ")) {
+			section = line.slice(3).trim();
+			continue;
+		}
+		const groups = LINK_LINE.exec(line.trim())?.groups;
+		if (groups?.title === void 0 || groups.href === void 0) continue;
+		const path = pagePathOf(groups.href, base);
+		if (path === null || seen.has(path)) continue;
+		seen.add(path);
+		entries.push(toEntry(baseUrl, path, groups.title, groups.description?.trim(), section));
+	}
+	return entries;
+}
+/** Parse Blume's `/api/docs/pages.json` into the same entries. */
+function parsePagesApi(source, baseUrl) {
+	const { pages } = pagesApiSchema.parse(JSON.parse(source));
+	return pages.filter((page) => page.route !== "/404").map((page) => toEntry(baseUrl, page.route.replace(/\/+$/u, "") || "/", page.title, page.description, page.contentType));
+}
+function parseLlmsFull(source, baseUrl) {
+	const base = new URL(baseUrl);
+	const lines = source.split("\n");
+	const starts = [];
+	for (let index = 1; index < lines.length; index++) {
+		const href = /^Source: (?<href>\S+)$/u.exec(lines[index] ?? "")?.groups?.href;
+		if (href === void 0 || !(lines[index - 1] ?? "").startsWith("# ")) continue;
+		const path = pagePathOf(href, base);
+		if (path !== null) starts.push({
+			path,
+			heading: index - 1
+		});
+	}
+	const bodies = /* @__PURE__ */ new Map();
+	starts.forEach((start, position) => {
+		const end = starts[position + 1]?.heading ?? lines.length;
+		bodies.set(start.path, lines.slice(start.heading + 2, end).join("\n").trim());
+	});
+	return bodies;
+}
+function toEntry(baseUrl, path, title, description, section) {
+	const entry = {
+		title,
+		path,
+		url: `${baseUrl}${path === "/" ? "" : path}`,
+		markdownUrl: `${baseUrl}${markdownPathFor(path)}`
+	};
+	if (description !== void 0 && description !== "") entry.description = description;
+	if (section !== void 0) entry.section = section;
+	return entry;
+}
+/** Blume writes `/docs.md` for `/docs` and `/index.md` for the home page. */
+function markdownPathFor(path) {
+	return path === "/" ? "/index.md" : `${path}.md`;
+}
+/**
+* Turn whatever an agent passes — a slug, a route, a full URL, with or
+* without `.md` — into a site-relative route.
+*/
+function toRoute(input) {
+	let value = input.trim();
+	if (/^https?:\/\//u.test(value)) value = new URL(value).pathname;
+	value = value.replace(/[?#].*$/u, "").replace(/\.mdx?$/u, "").replace(/\/+$/u, "");
+	if (value === "" || value === "/index") return "/";
+	return value.startsWith("/") ? value : `/${value}`;
+}
+function terms(query) {
+	return query.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((term) => term.length > 0);
+}
+function countOccurrences(haystack, needle) {
+	let count = 0;
+	let index = haystack.indexOf(needle);
+	while (index !== -1) {
+		count++;
+		index = haystack.indexOf(needle, index + needle.length);
+	}
+	return count;
+}
+function excerptOf(body, query, words) {
+	const lines = body.split("\n").map((line) => line.trim());
+	const lowered = lines.map((line) => line.toLowerCase());
+	const phrase = query.trim().toLowerCase();
+	const tests = [
+		(line) => line.includes(phrase),
+		(line) => words.every((word) => line.includes(word)),
+		(line) => words.some((word) => line.includes(word))
+	];
+	for (const test of tests) {
+		const index = lowered.findIndex(test);
+		const line = lines[index];
+		if (index !== -1 && line !== void 0) return line.length > 200 ? `${line.slice(0, 197)}...` : line;
+	}
+}
+/**
+* Rank entries against a keyword query. Every term has to appear somewhere —
+* the title, the route, the description, the section or (when given) the
+* body — and where it appears decides the weight.
+*/
+function rankEntries(entries, query, bodies) {
+	const words = terms(query);
+	if (words.length === 0) return [];
+	const phrase = words.join(" ");
+	const hits = [];
+	for (const entry of entries) {
+		const title = entry.title.toLowerCase();
+		const titleWords = new Set(terms(entry.title));
+		const route = entry.path.toLowerCase();
+		const description = (entry.description ?? "").toLowerCase();
+		const section = (entry.section ?? "").toLowerCase();
+		const body = bodies?.get(entry.path)?.toLowerCase() ?? "";
+		let score = title === phrase ? 20 : title.includes(phrase) ? 8 : 0;
+		let everyTermFound = true;
+		for (const word of words) {
+			let weight = 0;
+			if (titleWords.has(word)) weight += 10;
+			else if (title.includes(word)) weight += 6;
+			if (route.includes(word)) weight += 4;
+			if (description.includes(word)) weight += 2;
+			if (section.includes(word)) weight += 1;
+			weight += Math.min(countOccurrences(body, word), 5);
+			if (weight === 0) {
+				everyTermFound = false;
+				break;
+			}
+			score += weight;
+		}
+		if (!everyTermFound) continue;
+		const hit = {
+			...entry,
+			score
+		};
+		const excerpt = body === "" ? void 0 : excerptOf(bodies?.get(entry.path) ?? "", query, words);
+		if (excerpt !== void 0) hit.excerpt = excerpt;
+		hits.push(hit);
+	}
+	return hits.toSorted((left, right) => right.score - left.score || left.path.localeCompare(right.path));
+}
+var _fetcher = /* @__PURE__ */ new WeakMap();
+var _ttl = /* @__PURE__ */ new WeakMap();
+var _now = /* @__PURE__ */ new WeakMap();
+var _cache = /* @__PURE__ */ new WeakMap();
+var _DocsClient_brand = /* @__PURE__ */ new WeakSet();
+var DocsClient = class {
+	constructor(options) {
+		_classPrivateMethodInitSpec(this, _DocsClient_brand);
+		_defineProperty(this, "baseUrl", void 0);
+		_classPrivateFieldInitSpec(this, _fetcher, void 0);
+		_classPrivateFieldInitSpec(this, _ttl, void 0);
+		_classPrivateFieldInitSpec(this, _now, void 0);
+		_classPrivateFieldInitSpec(this, _cache, /* @__PURE__ */ new Map());
+		this.baseUrl = normaliseBaseUrl(options.baseUrl);
+		_classPrivateFieldSet2(_fetcher, this, options.fetcher ?? ((url) => fetch(url, { signal: AbortSignal.timeout(15e3) })));
+		_classPrivateFieldSet2(_ttl, this, options.ttl ?? 3e5);
+		_classPrivateFieldSet2(_now, this, options.now ?? Date.now);
+	}
+	/** Every page the site lists, in the order `llms.txt` lists them. */
+	async listDocs() {
+		const llms = await _assertClassBrand(_DocsClient_brand, this, _get).call(this, "/llms.txt");
+		if (llms !== null) return parseLlmsTxt(llms, this.baseUrl);
+		const api = await _assertClassBrand(_DocsClient_brand, this, _get).call(this, "/api/docs/pages.json");
+		if (api !== null) return parsePagesApi(api, this.baseUrl);
+		throw new DocsRequestError(`${this.baseUrl}/llms.txt`, 404);
+	}
+	async searchDocs(query, includeContent) {
+		const entries = await this.listDocs();
+		const bodies = includeContent ? await _assertClassBrand(_DocsClient_brand, this, _bodies).call(this) : null;
+		return {
+			searchedContent: bodies !== null,
+			hits: rankEntries(entries, query, bodies ?? void 0)
+		};
+	}
+	/**
+	* One page's Markdown. A bare slug (`button`) is matched against the index
+	* first — the last segment of a route — then tried under `/docs/`.
+	*/
+	async getDoc(input) {
+		const route = toRoute(input);
+		const entries = await this.listDocs().catch(() => []);
+		const slug = route.slice(1);
+		const known = new Set(entries.map((entry) => entry.path));
+		const guesses = [
+			route,
+			`/docs${route}`,
+			...entries.filter((entry) => entry.path.endsWith(route)).map((entry) => entry.path)
+		];
+		const candidates = /* @__PURE__ */ new Set([...guesses.filter((path) => known.has(path)), ...guesses]);
+		for (const path of candidates) {
+			const markdown = await _assertClassBrand(_DocsClient_brand, this, _get).call(this, markdownPathFor(path));
+			if (markdown !== null) return {
+				found: true,
+				entry: entries.find((candidate) => candidate.path === path) ?? toEntry(this.baseUrl, path, path, void 0, void 0),
+				markdown
+			};
+		}
+		return {
+			found: false,
+			path: route,
+			suggestions: rankEntries(entries, terms(slug).map((word) => word.slice(0, Math.max(4, word.length - 2))).join(" ")).slice(0, 5)
+		};
+	}
+};
+/**
+* A cached GET. `null` means the site answered 404 — a fact worth caching
+* too; any other failure throws and is not cached, so the next call retries.
+*/
+async function _get(path) {
+	const url = `${this.baseUrl}${path}`;
+	const cached = _classPrivateFieldGet2(_cache, this).get(url);
+	if (cached !== void 0 && cached.expires > _classPrivateFieldGet2(_now, this).call(this)) return cached.value;
+	const value = _classPrivateFieldGet2(_fetcher, this).call(this, url).then(async (response) => {
+		if (response.status === 404) return null;
+		if (!response.ok) throw new DocsRequestError(url, response.status);
+		return response.text();
+	});
+	if (_classPrivateFieldGet2(_ttl, this) > 0) {
+		_classPrivateFieldGet2(_cache, this).set(url, {
+			expires: _classPrivateFieldGet2(_now, this).call(this) + _classPrivateFieldGet2(_ttl, this),
+			value
+		});
+		value.catch(() => _classPrivateFieldGet2(_cache, this).delete(url));
+	}
+	return value;
+}
+/** Page bodies keyed by route, or `null` when the site has no `llms-full.txt`. */
+async function _bodies() {
+	const full = await _assertClassBrand(_DocsClient_brand, this, _get).call(this, "/llms-full.txt");
+	return full === null ? null : parseLlmsFull(full, this.baseUrl);
+}
+
+// src/server.ts
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 50;
+/** A tool answering in prose or Markdown. */
+function text(message) {
+	return { content: [{
+		type: "text",
+		text: message
+	}] };
+}
+/** A tool reporting a failure the agent should read rather than retry blindly. */
+function failure(message) {
+	return {
+		...text(message),
+		isError: true
+	};
+}
+function asJson(value) {
+	return JSON.stringify(value, null, 2);
+}
+function createServer(docs) {
+	const server = new McpServer({
+		name: "newtui-docs",
+		version
+	});
+	server.registerTool("list_docs", {
+		title: "List documentation pages",
+		description: "Every page of the newt/ui documentation (Discord-inspired components for React, Vue and HTML/CSS) with its title, route, description and section. Use it to find the page to read with get_doc.",
+		inputSchema: { section: z.string().optional().describe("Only pages listed under this section, e.g. 'Installation' or 'Forms'. Case-insensitive.") },
+		annotations: {
+			readOnlyHint: true,
+			openWorldHint: true
+		}
+	}, async ({ section }) => {
+		const all = await docs.listDocs();
+		const pages = section === void 0 ? all : all.filter((page) => page.section?.toLowerCase() === section.toLowerCase());
+		return text(asJson({
+			site: docs.baseUrl,
+			count: pages.length,
+			pages
+		}));
+	});
+	server.registerTool("search_docs", {
+		title: "Search the documentation",
+		description: "Keyword search over the newt/ui docs. Ranks pages by where every query term appears: title first, then route, description and section. Set content to true to search page bodies as well — slower, but it finds a prop or a token mentioned only inside a page.",
+		inputSchema: {
+			query: z.string().min(1).describe("Keywords, e.g. 'dark mode' or 'nuxt install'."),
+			content: z.boolean().optional().describe("Also search the full text of every page."),
+			limit: z.number().int().min(1).max(MAX_LIMIT).optional().describe(`How many results to return. Defaults to ${DEFAULT_LIMIT}.`)
+		},
+		annotations: {
+			readOnlyHint: true,
+			openWorldHint: true
+		}
+	}, async ({ query, content, limit }) => {
+		const result = await docs.searchDocs(query, content ?? false);
+		const results = result.hits.slice(0, limit ?? DEFAULT_LIMIT);
+		return text(asJson({
+			site: docs.baseUrl,
+			query,
+			searchedContent: result.searchedContent,
+			count: results.length,
+			results
+		}));
+	});
+	server.registerTool("get_doc", {
+		title: "Read a documentation page",
+		description: "One page of the newt/ui docs as Markdown. Accepts a route ('/docs/theming'), a slug ('button', 'installation/nuxt') or a full newtui.dev URL. Read this rather than recalling an API from memory.",
+		inputSchema: { path: z.string().min(1).describe("The page: a route, a slug or a URL.") },
+		annotations: {
+			readOnlyHint: true,
+			openWorldHint: true
+		}
+	}, async ({ path }) => {
+		const page = await docs.getDoc(path);
+		if (!page.found) return failure(`No documentation page at "${page.path}". Closest matches:\n\n${asJson({
+			site: docs.baseUrl,
+			path: page.path,
+			suggestions: page.suggestions
+		})}`);
+		return text(`<!-- Source: ${page.entry.url} -->\n\n${page.markdown}`);
+	});
+	return server;
+}
+/** Serve over stdio, which is how every MCP client launches a local server. */
+async function startServer(docs) {
+	await createServer(docs).connect(new StdioServerTransport());
+}
+
+// src/index.ts
+const HELP = `newtui-mcp — an MCP server for the newt/ui documentation
+
+Usage
+  $ npx @newtui/mcp [--url <site>]
+
+Options
+  --url <site>   the docs site to read (default: ${DEFAULT_DOCS_URL})
+                 also read from NEWTUI_DOCS_URL
+  -h, --help     show this help
+  -v, --version  print the version
+
+The server speaks MCP over stdio; an editor launches it, not a person.`;
+async function main() {
+	const { values } = parseArgs({ options: {
+		url: { type: "string" },
+		help: {
+			type: "boolean",
+			short: "h"
+		},
+		version: {
+			type: "boolean",
+			short: "v"
+		}
+	} });
+	if (values.help === true) {
+		console.log(HELP);
+		return;
+	}
+	if (values.version === true) {
+		console.log(version);
+		return;
+	}
+	const baseUrl = resolveDocsUrl(values.url, process.env.NEWTUI_DOCS_URL);
+	let docs;
+	try {
+		docs = new DocsClient({ baseUrl });
+	} catch {
+		console.error(`newtui-mcp: "${baseUrl}" is not a URL.`);
+		process.exit(1);
+	}
+	await startServer(docs);
+}
+main().catch((error) => {
+	console.error(`newtui-mcp: ${error instanceof Error ? error.message : String(error)}`);
+	process.exit(1);
+});
+
+export {  };

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@newtui/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "MCP server for the newt/ui documentation — lets a coding agent list, search and read the Discord-inspired component library's docs. Part of the WolfStar toolchain.",
+  "keywords": [
+    "component-library",
+    "design-system",
+    "discord",
+    "documentation",
+    "mcp",
+    "model-context-protocol",
+    "ui",
+    "wolfstar"
+  ],
+  "homepage": "https://newtui.dev/docs/mcp",
+  "bugs": {
+    "url": "https://github.com/wolfstar-project/newt-ui/issues"
+  },
+  "license": "Apache-2.0",
+  "author": "@wolfstar",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wolfstar-project/newt-ui.git",
+    "directory": "packages/mcp"
+  },
+  "bin": {
+    "newtui-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsdown": "^0.23.5",
+    "typescript": "^5.7.2",
+    "unrun": "^0.3.1",
+    "vitest": "^5.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsdown --config-loader unrun",
+    "dev": "tsdown --config-loader unrun --watch",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
 }