react-native-docs-mcp 0.1.0 → 0.2.0

package/README.md

@@ -52,12 +52,15 @@ Edit: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 
 ## Features
 
+- **🔑 No API Key**: Unlike hosted docs services (Context7, GitMCP), everything runs on your machine — no account, no key, no rate limits
+- **🔌 Works Offline**: Clones the official react-native-website docs repo once, then searches locally — no network calls at query time
 - **🔍 Semantic Search**: AI-powered search using embeddings for conceptual matches
 - **⚡ Fast Results**: In-memory vector search with hybrid keyword+semantic ranking
 - **📦 Zero Config**: Works with `npx` - no installation needed
 - **🤖 Local AI**: Runs embeddings locally (no API costs)
 - **📝 Concise Responses**: Returns summaries instead of full documentation
 - **🔄 Auto-sync**: Pulls latest docs from the react-native-website repo automatically
+- **📌 Version Pinning**: `--docs-version=0.77` scopes docs to the React Native release your app actually uses
 
 ## Usage
 
@@ -88,6 +91,7 @@ Get a specific documentation page.
 **Parameters**:
 
 - `path` (required): Document path (e.g., "getting-started", "the-new-architecture/using-codegen")
+- `full` (optional): Return the full raw page instead of the ~1500 char summary (default: false)
 
 **Example**:
 
@@ -95,6 +99,13 @@ Get a specific documentation page.
 Get the React Native flexbox documentation
 ```
 
+**Why `full`?** The default summary is enough for most reference pages, but long guides — like "The New Architecture" migration docs, or a full native-modules walkthrough — can run well past 1500 chars, and the summary may stop before the part you actually need. Ask for the complete page when that happens:
+
+```
+Get the full page for the-new-architecture/using-codegen, I need every step
+```
+which calls `get_doc` with `{ "path": "the-new-architecture/using-codegen", "full": true }`.
+
 #### `list_sections`
 
 List all available documentation sections.
@@ -103,6 +114,26 @@ List all available documentation sections.
 
 Pull latest documentation from the Git repository.
 
+### Docs version
+
+By default this server indexes the always-current `docs/` folder from the react-native-website repo — the same docs shown on reactnative.dev today. To pin it to a specific past release's frozen docs snapshot instead, pass `--docs-version`:
+
+```bash
+npx react-native-docs-mcp --docs-version=0.77
+```
+
+or set the `REACT_NATIVE_DOCS_VERSION` env var (the CLI flag wins if both are set). With Claude Code:
+
+```bash
+claude mcp add --transport stdio react-native-docs -- npx react-native-docs-mcp --docs-version=0.77
+```
+
+(Bare `--version` prints the package version, as you'd expect from any CLI.)
+
+**Why pin a version?** If your app is running React Native 0.77 but the agent searches always-current docs, it can suggest an API that only exists in 0.86, or miss that something was renamed/removed since your version. Pinning `--docs-version` to match your `react-native` dependency's version keeps suggestions consistent with the APIs actually available in your app — useful when working on an app that's a few releases behind latest, or when debugging something version-specific (e.g. "did this New Architecture behavior change between 0.78 and 0.82?" — run two instances, one per version, and compare).
+
+Only `latest` (the default) is fully verified against the current docs structure; older version snapshots are indexed best-effort with the same settings.
+
 ### Resources
 
 The server exposes documentation as resources with the URI pattern:

package/dist/index.js

@@ -3,6 +3,59 @@
 // ../../src/config.ts
 import { homedir } from "os";
 import { join } from "path";
+
+// ../../src/presets/searchDefaults.ts
+var DEFAULT_SEARCH = {
+  defaultLimit: 10,
+  maxLimit: 50,
+  minScore: 0.1,
+  semanticSearchEnabled: true,
+  semanticMinSimilarity: 0.3,
+  hybridKeywordWeight: 0.3,
+  hybridSemanticWeight: 0.7
+};
+
+// ../../src/presets/reactDocs.ts
+var reactDocsPreset = {
+  cacheDirName: "react-docs-mcp",
+  repoFolderName: "react-dev-repo",
+  repo: {
+    url: "https://github.com/reactjs/react.dev.git",
+    contentPath: "src/content"
+  },
+  search: { ...DEFAULT_SEARCH },
+  server: {
+    name: "react-docs-mcp",
+    version: "1.2.0"
+  },
+  sections: ["learn", "reference", "blog", "community"],
+  resourceUriScheme: "react-docs",
+  docsLabel: "React",
+  searchToolName: "search_react_docs",
+  searchToolDescription: "Search across React documentation. Returns relevant documentation pages with snippets.",
+  pathExample: "reference/react/useState",
+  docUrl: { base: "https://react.dev", useFrontmatterId: false },
+  sectionResourceOverrides: {
+    learn: {
+      name: "React Learn Documentation",
+      description: "Interactive React tutorial and learning materials"
+    },
+    reference: {
+      name: "React API Reference",
+      description: "Complete React API reference documentation"
+    },
+    blog: {
+      name: "React Blog",
+      description: "React team blog posts and announcements"
+    },
+    community: {
+      name: "React Community Documentation",
+      description: "Community resources, code of conduct, and translations"
+    }
+  }
+};
+
+// ../../src/config.ts
 var getCacheDir = (cacheDirName) => {
   const platform = process.platform;
   const home = homedir();
@@ -24,66 +77,46 @@ function resolve(preset) {
     }
   };
 }
-var defaultPreset = {
-  cacheDirName: "react-docs-mcp",
-  repoFolderName: "react-dev-repo",
-  repo: {
-    url: "https://github.com/reactjs/react.dev.git",
-    contentPath: "src/content"
-  },
-  search: {
-    defaultLimit: 10,
-    maxLimit: 50,
-    minScore: 0.1,
-    semanticSearchEnabled: true,
-    semanticMinSimilarity: 0.3,
-    hybridKeywordWeight: 0.3,
-    hybridSemanticWeight: 0.7
-  },
-  server: {
-    name: "react-docs-mcp",
-    version: "1.0.0"
-  },
-  sections: ["learn", "reference", "blog", "community"],
-  resourceUriScheme: "react-docs",
-  docsLabel: "React",
-  searchToolName: "search_react_docs",
-  searchToolDescription: "Search across React documentation. Returns relevant documentation pages with snippets.",
-  docUrl: { base: "https://react.dev", useFrontmatterId: false }
-};
-var activeConfig = resolve(defaultPreset);
+var activeConfig = resolve(reactDocsPreset);
 function configure(preset) {
   activeConfig = resolve(preset);
 }
 
 // ../../src/presets/reactNativeDocs.ts
-var reactNativeDocsPreset = {
-  cacheDirName: "react-native-docs-mcp",
-  repoFolderName: "react-native-website-repo",
-  repo: {
-    url: "https://github.com/facebook/react-native-website.git",
-    contentPath: "docs"
-  },
-  search: {
-    defaultLimit: 10,
-    maxLimit: 50,
-    minScore: 0.1,
-    semanticSearchEnabled: true,
-    semanticMinSimilarity: 0.3,
-    hybridKeywordWeight: 0.3,
-    hybridSemanticWeight: 0.7
-  },
-  server: {
-    name: "react-native-docs-mcp",
-    version: "0.1.0"
-  },
-  sections: ["the-new-architecture", "legacy", "releases"],
-  resourceUriScheme: "react-native-docs",
-  docsLabel: "React Native",
-  searchToolName: "search_react_native_docs",
-  searchToolDescription: "Search across React Native documentation. Returns relevant documentation pages with snippets.",
-  docUrl: { base: "https://reactnative.dev/docs", useFrontmatterId: true }
-};
+var LATEST_VERSION = "latest";
+function resolveReactNativeDocsPreset(version = LATEST_VERSION) {
+  const isLatest = version === LATEST_VERSION;
+  if (!isLatest && !/^\d+\.\d+$/.test(version)) {
+    throw new Error(
+      `Invalid React Native docs version "${version}". Expected a release like "0.77" or "${LATEST_VERSION}".`
+    );
+  }
+  return {
+    cacheDirName: "react-native-docs-mcp",
+    repoFolderName: "react-native-website-repo",
+    repo: {
+      url: "https://github.com/facebook/react-native-website.git",
+      contentPath: isLatest ? "docs" : `website/versioned_docs/version-${version}`
+    },
+    search: { ...DEFAULT_SEARCH },
+    server: {
+      name: "react-native-docs-mcp",
+      version: "0.2.0"
+    },
+    sections: ["the-new-architecture", "legacy", "releases"],
+    resourceUriScheme: "react-native-docs",
+    docsLabel: "React Native",
+    searchToolName: "search_react_native_docs",
+    searchToolDescription: "Search across React Native documentation. Returns relevant documentation pages with snippets.",
+    pathExample: "the-new-architecture/using-codegen",
+    docUrl: {
+      base: isLatest ? "https://reactnative.dev/docs" : `https://reactnative.dev/docs/${version}`,
+      // Frontmatter-id routing is a property of the Docusaurus content format,
+      // not of the version — versioned snapshots carry the same id overrides
+      useFrontmatterId: true
+    }
+  };
+}
 
 // ../../src/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -118,12 +151,19 @@ var DocsManager = class {
   async initialize() {
     const repoExists = await this.checkRepoExists();
     if (!repoExists) {
-      console.log("Cloning React documentation repository...");
+      console.log("Cloning documentation repository...");
       await this.cloneRepo();
       console.log("Repository cloned successfully");
     } else {
       console.log("Repository already exists");
     }
+    try {
+      await fs.access(this.contentPath);
+    } catch {
+      throw new Error(
+        `Docs content path not found: ${this.contentPath}. The cloned repository has no such folder \u2014 if you passed --docs-version, check that this docs version exists.`
+      );
+    }
   }
   /**
    * Check if repository exists locally
@@ -137,16 +177,33 @@ var DocsManager = class {
     }
   }
   /**
-   * Clone the repository
+   * Clone the repository.
+   * Clones into a temp directory and renames into place so that two
+   * processes starting on a fresh machine (e.g. two MCP servers sharing one
+   * cache) don't corrupt each other; the loser discards its redundant copy.
    */
   async cloneRepo() {
+    const tempPath = `${this.repoPath}.cloning-${process.pid}`;
     try {
       await fs.mkdir(path.dirname(this.repoPath), { recursive: true });
-      await this.git.clone(activeConfig.repo.url, this.repoPath, {
+      await this.git.clone(activeConfig.repo.url, tempPath, {
         "--depth": 1
         // Shallow clone for faster download
       });
+      try {
+        await fs.rename(tempPath, this.repoPath);
+      } catch (renameError) {
+        if (await this.checkRepoExists()) {
+          await fs.rm(tempPath, { recursive: true, force: true });
+          return;
+        }
+        throw renameError;
+      }
     } catch (error) {
+      try {
+        await fs.rm(tempPath, { recursive: true, force: true });
+      } catch {
+      }
       throw new Error(
         `Failed to clone repository: ${error instanceof Error ? error.message : String(error)}`
       );
@@ -243,6 +300,25 @@ var DocsManager = class {
     this.fileCache.set(cacheKey, files);
     return files;
   }
+  /**
+   * Filter a list of section names down to those whose directory actually
+   * exists under the content root. Lets the server avoid advertising
+   * sections that are empty in the checked-out docs (e.g. a versioned
+   * snapshot that predates a section).
+   */
+  async getExistingSections(sections) {
+    const checks = await Promise.all(
+      sections.map(async (section) => {
+        try {
+          await fs.access(path.join(this.contentPath, section));
+          return section;
+        } catch {
+          return null;
+        }
+      })
+    );
+    return checks.filter((section) => section !== null);
+  }
   /**
    * Read file content
    * @param relativePath - Path relative to content root
@@ -309,11 +385,14 @@ function extractSection(path2) {
 function normalizePath(filePath) {
   return filePath.replace(/\\/g, "/").replace(/^\/+/, "").replace(/\.mdx?$/, "");
 }
+function titleCase(slug) {
+  return slug.replace(/[-_]/g, " ").split(" ").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
 function extractTitleFromPath(filePath) {
   const normalized = normalizePath(filePath);
   const parts = normalized.split("/");
   const filename = parts[parts.length - 1] || "Untitled";
-  return filename.replace(/[-_]/g, " ").split(" ").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+  return titleCase(filename);
 }
 
 // ../../src/embeddingService.ts
@@ -415,6 +494,17 @@ var EmbeddingService = class {
 };
 
 // ../../src/searchEngine.ts
+function resolveDocSlug(path2, id) {
+  if (typeof id !== "string" || id.length === 0) {
+    return path2;
+  }
+  if (id.includes("/")) {
+    return id;
+  }
+  const parts = path2.split("/");
+  parts[parts.length - 1] = id;
+  return parts.join("/");
+}
 var SearchEngine = class {
   docsManager;
   embeddingService;
@@ -441,12 +531,16 @@ var SearchEngine = class {
       try {
         const content = await this.docsManager.readDoc(docPath);
         const parsedDoc = await parseMarkdown(content, docPath);
+        if (activeConfig.docUrl.useFrontmatterId) {
+          parsedDoc.path = resolveDocSlug(parsedDoc.path, parsedDoc.metadata.id);
+        }
         this.documentIndex.set(parsedDoc.path, parsedDoc);
       } catch (error) {
         console.warn(`Failed to index document ${docPath}:`, error);
       }
     }
     this.indexed = true;
+    this.embeddingsGenerated = false;
     console.log(`Indexed ${this.documentIndex.size} documents`);
   }
   /**
@@ -615,14 +709,7 @@ var SearchEngine = class {
     if (!this.indexed) {
       await this.indexDocuments();
     }
-    const normalizedPath = path2.replace(/\.mdx?$/, "");
-    return this.documentIndex.get(normalizedPath) || null;
-  }
-  /**
-   * List all available sections
-   */
-  getSections() {
-    return [...activeConfig.sections];
+    return this.documentIndex.get(normalizePath(path2)) || null;
   }
   /**
    * Get all documents in a section
@@ -690,22 +777,11 @@ function extractStructure(content) {
 }
 
 // ../../src/server.ts
-function titleCase(section) {
-  return section.split(/[-_]/).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+function escapeRegExp(literal) {
+  return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 function buildDocUrl(doc) {
-  let slug = doc.path;
-  const id = doc.metadata.id;
-  if (activeConfig.docUrl.useFrontmatterId && id) {
-    if (id.includes("/")) {
-      slug = id;
-    } else {
-      const parts = doc.path.split("/");
-      parts[parts.length - 1] = id;
-      slug = parts.join("/");
-    }
-  }
-  return `${activeConfig.docUrl.base}/${slug}`;
+  return `${activeConfig.docUrl.base}/${doc.path}`;
 }
 async function createServer() {
   const docsManager = new DocsManager();
@@ -724,16 +800,20 @@ async function createServer() {
   );
   const searchDocsSchema = z.object({
     query: z.string().describe("Search query string"),
-    section: z.string().optional().describe(`Filter by section (${activeConfig.sections.join(", ")})`),
+    section: z.string().optional().refine((section) => section === void 0 || activeConfig.sections.includes(section), {
+      message: `Unknown section. Valid sections: ${activeConfig.sections.join(", ")}`
+    }).describe(`Filter by section (${activeConfig.sections.join(", ")})`),
     limit: z.number().min(1).max(activeConfig.search.maxLimit).optional().describe("Maximum number of results")
   });
   const getDocSchema = z.object({
-    path: z.string().describe('Document path (e.g., "learn/hooks/useState")')
+    path: z.string().describe(`Document path (e.g., "${activeConfig.pathExample}")`),
+    full: z.boolean().optional().describe("Return the full raw page content instead of a ~1500 char summary")
   });
-  const resourceUriRegex = new RegExp(`^${activeConfig.resourceUriScheme}:\\/\\/(.+)$`);
+  const resourceUriRegex = new RegExp(`^${escapeRegExp(activeConfig.resourceUriScheme)}:\\/\\/(.+)$`);
   server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    const existingSections = await docsManager.getExistingSections(activeConfig.sections);
     return {
-      resources: activeConfig.sections.map((section) => {
+      resources: existingSections.map((section) => {
         const override = activeConfig.sectionResourceOverrides?.[section];
         return {
           uri: `${activeConfig.resourceUriScheme}://${section}`,
@@ -822,13 +902,17 @@ ${doc.content}`
         },
         {
           name: "get_doc",
-          description: `Get a concise summary of a documentation page (~1500 chars). Use ${activeConfig.searchToolName} first - only call this if you need more detail than the search snippet provides.`,
+          description: `Get a concise summary of a documentation page (~1500 chars), or the full raw page with full:true. Use ${activeConfig.searchToolName} first - only call this if you need more detail than the search snippet provides.`,
           inputSchema: {
             type: "object",
             properties: {
               path: {
                 type: "string",
-                description: 'Document path (e.g., "learn/hooks/useState")'
+                description: `Document path (e.g., "${activeConfig.pathExample}")`
+              },
+              full: {
+                type: "boolean",
+                description: "Return the full raw page content instead of a ~1500 char summary"
               }
             },
             required: ["path"]
@@ -872,7 +956,7 @@ ${doc.content}`
           };
         }
         case "list_sections": {
-          const sections = searchEngine.getSections();
+          const sections = await docsManager.getExistingSections(activeConfig.sections);
           return {
             content: [
               {
@@ -883,13 +967,16 @@ ${doc.content}`
           };
         }
         case "get_doc": {
-          const { path: path2 } = getDocSchema.parse(args);
+          const { path: path2, full } = getDocSchema.parse(args);
           const doc = await searchEngine.getDocByPath(path2);
           if (!doc) {
             throw new Error(`Document not found: ${path2}`);
           }
-          const summary = summarizeContent(doc.content, 1500);
-          const structure = extractStructure(doc.content);
+          const body = full ? { content: doc.content, note: "Full page content." } : {
+            summary: summarizeContent(doc.content, 1500),
+            structure: extractStructure(doc.content),
+            note: "This is a summary. Pass full:true for the complete page, or visit the URL."
+          };
           return {
             content: [
               {
@@ -900,10 +987,8 @@ ${doc.content}`
                     section: doc.section,
                     title: doc.metadata.title,
                     description: doc.metadata.description,
-                    summary,
-                    structure,
-                    url: buildDocUrl(doc),
-                    note: "This is a summary. Visit the URL for full documentation."
+                    ...body,
+                    url: buildDocUrl(doc)
                   },
                   null,
                   2
@@ -951,7 +1036,33 @@ ${doc.content}`
 }
 
 // src/index.ts
-configure(reactNativeDocsPreset);
+var argv = process.argv.slice(2);
+if (argv.includes("--version") || argv.includes("-v")) {
+  console.log(resolveReactNativeDocsPreset().server.version);
+  process.exit(0);
+}
+function parseDocsVersionArg(args) {
+  for (const arg of args) {
+    const match = arg.match(/^--docs-version=(.+)$/);
+    if (match) return match[1];
+  }
+  const flagIndex = args.indexOf("--docs-version");
+  const value = flagIndex !== -1 ? args[flagIndex + 1] : void 0;
+  if (value && !value.startsWith("-")) {
+    return value;
+  }
+  return void 0;
+}
+var docsVersion = parseDocsVersionArg(argv) ?? process.env.REACT_NATIVE_DOCS_VERSION ?? LATEST_VERSION;
+if (docsVersion !== LATEST_VERSION) {
+  console.error(`Using React Native docs version: ${docsVersion} (best-effort; only "latest" is fully verified)`);
+}
+try {
+  configure(resolveReactNativeDocsPreset(docsVersion));
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
 createServer().catch((error) => {
   console.error("Failed to start server:", error);
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-docs-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server providing AI agents with semantic search over React Native documentation",
   "main": "dist/index.js",
   "type": "module",