feat: introduce @lynx-js/docs-mcp-server

.changeset/public-carrots-search.md

@@ -0,0 +1,3 @@
+---
+
+---

packages/mcp-servers/docs-mcp-server/README.md

@@ -0,0 +1,109 @@
+# @lynx-js/docs-mcp-server
+
+> A MCP Server providing Lynx documentation resources for LLMs, with carefully designed prompting.
+
+`@lynx-js/docs-mcp-server` lets your coding agent (such as Gemini, Claude, Cursor or Copilot)
+access Lynx documentation to assist you in development tasks. Therefore,
+we have specifically optimized [llms.txt](https://lynxjs.org/next/llms.txt),
+a condensed version of the documentation site optimized for reading large models.
+
+## Requirements
+
+- [Node.js](https://nodejs.org/) v18.17 or a newer [latest maintenance LTS](https://github.com/nodejs/Release#release-schedule) version.
+
+## Getting started
+
+Add the following config to your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "lynx-docs": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@lynx-js/docs-mcp-server@latest"
+      ]
+    }
+  }
+}
+```
+
+`@lynx-js/docs-mcp-server` works best with MCP clients that supports [Server Instructions](https://modelcontextprotocol.io/specification/draft/schema#initializeresult), such as Claude Code.
+If you find your MCP client don't know about the MCP server,
+you can manually provide the following instructions
+(e.g. in your `AGENTS.md`, `CLAUDE.md`, or just send it along with your question):
+
+```md
+For any questions or requirements regarding Lynx:
+
+1. Use the "List Resources Tool" to list all Resources provided in MCP "lynx-docs".
+2. First read MCP Resources "lynx-docs://llms.txt" (**REQUIRED**), this document is an ENTRYPOINT of all Lynx Docs.
+3. After reading "lynx-docs://llms.txt", use the "Read MCP Resources Tool" to retrieve docs you need based on the user's questions or requirements, please read them proactively.
+4. If available, prioritize obtaining Lynx-related information through MCP Resources tools over external web searches.
+```
+
+<details>
+  <summary>Claude Code</summary>
+    Use the Claude Code CLI to add the Lynx Docs MCP server (<a href="https://docs.anthropic.com/en/docs/claude-code/mcp">guide</a>):
+
+```bash
+claude mcp add lynx-docs npx @lynx-js/docs-mcp-server@latest
+```
+
+</details>
+
+<details>
+  <summary>Codex</summary>
+  Follow the <a href="https://github.com/openai/codex/blob/main/docs/advanced.md#model-context-protocol-mcp">configure MCP guide</a>
+  using the standard config from above. You can also install the Lynx Docs MCP server using the Codex CLI:
+
+```bash
+codex mcp add lynx-docs -- npx @lynx-js/docs-mcp-server@latest
+```
+
+</details>
+
+<details>
+  <summary>Copilot / VS Code</summary>
+  Follow the MCP install <a href="https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server">guide</a>,
+  with the standard config from above. You can also install the Lynx Docs MCP server using the VS Code CLI:
+
+```bash
+code --add-mcp '{"name":"lynx-docs","command":"npx","args":["@lynx-js/docs-mcp-server@latest"]}'
+```
+
+</details>
+
+<details>
+  <summary>Cursor</summary>
+
+**Install manually:**
+
+Go to `Cursor Settings` -> `MCP` -> `New MCP Server`. Use the config provided above.
+
+</details>
+
+<details>
+  <summary>Gemini CLI</summary>
+Install the Lynx Docs MCP server using the Gemini CLI.
+
+**Project wide:**
+
+```bash
+gemini mcp add lynx-docs npx @lynx-js/docs-mcp-server@latest
+```
+
+**Globally:**
+
+```bash
+gemini mcp add -s user lynx-docs npx @lynx-js/docs-mcp-server@latest
+```
+
+Alternatively, follow the <a href="https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#how-to-set-up-your-mcp-server">MCP guide</a> and use the standard config from above.
+
+</details>
+
+## Credits
+
+This project is inspired by [Svelte MCP server](https://svelte.dev/docs/mcp/overview). Both the implementation and documentation have been adapted and referenced from the original MCP server.

packages/mcp-servers/docs-mcp-server/main.ts

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+
+// Copyright 2025 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+import { readFile } from 'node:fs/promises';
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { Command } from 'commander';
+import createDebug from 'debug';
+import * as findPackage from 'empathic/package';
+import type { Link, Node } from 'mdast';
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { toMarkdown } from 'mdast-util-to-markdown';
+import { fetch } from 'undici';
+
+// NOTE: Un comment below to enable caching and debug for undici fetch requests
+// import {
+//   interceptors,
+//   EnvHttpProxyAgent
+//   setGlobalDispatcher,
+//   // @ts-expect-error missing types
+//   cacheStores,
+// } from 'undici';
+// const agent = new EnvHttpProxyAgent().compose(
+//   interceptors.cache({
+//     store: new cacheStores.MemoryCacheStore({
+//       maxSize: 100 * 1024 * 1024, // 100MB
+//       maxCount: 1000,
+//       maxEntrySize: 5 * 1024 * 1024, // 5MB
+//     }),
+//     methods: ['GET', 'HEAD'], // Optional: specify which methods to cache
+//   }),
+// );
+// setGlobalDispatcher(agent);
+
+const debug = createDebug('lynx-docs-mcp');
+
+const pkgPath = findPackage.up({ cwd: new URL('.', import.meta.url).pathname });
+const pkg = JSON.parse(await readFile(pkgPath!, 'utf-8')) as {
+  version: string;
+  name: string;
+  description: string;
+};
+
+const MCP_SERVER_NAME = 'lynx-docs';
+
+function registerResources(
+  baseURL: string,
+  mcpServer: McpServer,
+  fromMarkdownText: string,
+) {
+  const tree = fromMarkdown(fromMarkdownText); // verify markdown is valid
+
+  const forEachLink = (node: Node, cb: (link: Link) => void) => {
+    if (node.type === 'link') {
+      cb(node as Link);
+    } else if ('children' in node && Array.isArray(node.children)) {
+      for (const child of node.children) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+        forEachLink(child, cb);
+      }
+    }
+  };
+
+  const linkUrls: Map<string, Link> = new Map();
+  forEachLink(tree, (link) => {
+    try {
+      const base = new URL(baseURL);
+      const u = new URL(link.url);
+      if (
+        u.hostname === base.hostname
+        // Some links may be absolute URLs to lynxjs.org
+        || u.hostname === 'lynxjs.org'
+      ) {
+        // Strip versioned path prefixes like /next/ or /1.2.3/
+        const strippedUrl = u.pathname.replace(
+          /^\/(?:next|\d+(?:\.\d+)*)?\/?/,
+          '',
+        );
+        linkUrls.set(strippedUrl, link);
+      }
+    } catch {
+      // Ignore invalid URLs
+    }
+  });
+
+  linkUrls.forEach((link, strippedUrl) => {
+    // Generate a title for the resource by converting the link node back to markdown
+    // NOTE: The title generation is complex because link titles may contain nested formatting, DON'T just use link.title
+    const title = toMarkdown({ ...link, type: 'root' }).trim();
+
+    if (!title) {
+      return;
+    }
+
+    debug(
+      `Registering resource: lynx-docs://${strippedUrl} from [${title}](${baseURL}/${strippedUrl})`,
+    );
+
+    mcpServer.registerResource(
+      title,
+      `lynx-docs://${strippedUrl}`,
+      {
+        title,
+        description: title,
+        mimeType: 'text/markdown',
+      },
+      async () => ({
+        contents: [
+          {
+            uri: `lynx-docs://${strippedUrl}`,
+            text: await fetch(link.url).then((res) => res.text()),
+            mimeType: 'text/markdown',
+          },
+        ],
+      }),
+    );
+  });
+}
+
+async function main(baseUrl: string) {
+  const ROOT_DOC_URL = `${baseUrl}/llms.txt`;
+  const ROOT_DOC_MARKDOWN = await fetch(ROOT_DOC_URL).then((res) => res.text());
+  const ROOT_DOC_RESOURCE_URI = 'lynx-docs://llms.txt';
+  const ROOT_DOC_TITLE = 'Read This Before Building with Lynx';
+  const ROOT_DOC_DESCRIPTION =
+    'Before building with Lynx, be sure to read this document to understand important information and best practices.';
+
+  const mcpServer = new McpServer({
+    name: MCP_SERVER_NAME,
+    version: pkg.version,
+  }, {
+    // NOTE: This instruction for now is not supported by Codex's MCP support,
+    // see https://github.com/openai/codex/issues/6148
+    instructions: `\
+<user_instructions>
+For any questions or requirements regarding Lynx:
+
+1. Use the "List Resources Tool" to list all Resources provided in MCP "${MCP_SERVER_NAME}".
+2. First read MCP Resources "${ROOT_DOC_RESOURCE_URI}" (**REQUIRED**), this document is an ENTRYPOINT of all Lynx Docs.
+3. After reading "${ROOT_DOC_RESOURCE_URI}", use the "Read MCP Resources Tool" to retrieve docs you need based on the user's questions or requirements, please read them proactively.
+4. If available, prioritize obtaining Lynx-related information through MCP Resources tools over external web searches.
+
+</user_instructions>
+`,
+  });
+
+  mcpServer.registerResource(
+    ROOT_DOC_TITLE,
+    ROOT_DOC_RESOURCE_URI,
+    {
+      title: ROOT_DOC_TITLE,
+      description: ROOT_DOC_DESCRIPTION,
+      mimeType: 'text/markdown',
+    },
+    () => ({
+      contents: [
+        {
+          uri: ROOT_DOC_RESOURCE_URI,
+          text: ROOT_DOC_MARKDOWN,
+          mimeType: 'text/markdown',
+        },
+      ],
+    }),
+  );
+
+  registerResources(baseUrl, mcpServer, ROOT_DOC_MARKDOWN);
+
+  const transport = new StdioServerTransport();
+  await mcpServer.connect(transport);
+}
+
+const program = new Command();
+
+program
+  .name(`npx -y ${pkg.name}`)
+  .description(pkg.description)
+  .option(
+    '--base-url <url>',
+    'Base URL for fetching Lynx docs. Set if you want versioned docs.',
+    'https://lynxjs.org/next/',
+  )
+  .version(pkg.version)
+  .addHelpText(
+    'after',
+    `
+Usage as a MCP Server:
+  {
+    "mcpServers": {
+      "${MCP_SERVER_NAME}": {
+        "command": "npx",
+        "args": ["-y", "${pkg.name}"]
+      }
+    }
+  }
+`,
+  )
+  .action(async (options: { baseUrl: string }) => {
+    await main(
+      // need to remove trailing slash if any
+      options.baseUrl.replace(/\/+$/, ''),
+    );
+  });
+
+program.parse(process.argv);

packages/mcp-servers/docs-mcp-server/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@lynx-js/docs-mcp-server",
+  "version": "0.2.1",
+  "description": "A MCP Server providing Lynx documentation resources for LLMs, with carefully designed prompting.",
+  "type": "module",
+  "bin": "./main.ts",
+  "files": [
+    "dist",
+    "main.ts"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.20.0",
+    "commander": "^13.1.0",
+    "debug": "^4.4.3",
+    "empathic": "^2.0.0",
+    "mdast-util-from-markdown": "^2.0.2",
+    "mdast-util-to-markdown": "^2.1.2",
+    "undici": "^6.22.0"
+  },
+  "devDependencies": {
+    "@types/debug": "^4.1.12",
+    "@types/mdast": "^4.0.4",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "publishConfig": {
+    "bin": "./dist/main.js"
+  }
+}

packages/mcp-servers/docs-mcp-server/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "allowImportingTsExtensions": false,
+    "isolatedDeclarations": false,
+    "emitDeclarationOnly": false,
+    "types": ["node"],
+    "outDir": "dist",
+  },
+  "include": ["src", "main.ts"],
+}