react-docs-mcp 1.0.0

package/README.md

@@ -0,0 +1,217 @@
+# React Docs MCP Server
+
+AI-powered semantic search over React documentation for Claude, Cursor, and other MCP clients.
+
+## 🚀 Installation (One Command)
+
+### Claude Code
+```bash
+claude mcp add --transport stdio react-docs -- npx react-docs-mcp
+```
+
+### Claude Desktop
+
+Edit: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
+
+```json
+{
+  "mcpServers": {
+    "react-docs": {
+      "command": "npx",
+      "args": ["-y", "react-docs-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+**Settings** → **Features** → **MCP** → Add server:
+```json
+{
+  "react-docs": {
+    "command": "npx",
+    "args": ["-y", "react-docs-mcp"]
+  }
+}
+```
+
+**That's it!** Restart your editor and ask about React.
+
+---
+
+## Features
+
+- **🔍 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 react.dev automatically
+
+## Configuration
+
+### For Claude Desktop
+
+Add to your Claude Desktop configuration file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "react-docs": {
+      "command": "node",
+      "args": ["/absolute/path/to/reactDocsMcp/dist/index.js"]
+    }
+  }
+}
+```
+
+### For Claude Code
+
+Add to your MCP settings configuration:
+
+```json
+{
+  "mcpServers": {
+    "react-docs": {
+      "command": "node",
+      "args": ["/absolute/path/to/reactDocsMcp/dist/index.js"]
+    }
+  }
+}
+```
+
+## Usage
+
+Once configured, the server provides the following capabilities to AI agents:
+
+### Tools
+
+#### `search_react_docs`
+
+Search across React documentation.
+
+**Parameters**:
+- `query` (required): Search query string
+- `section` (optional): Filter by section (learn, reference, blog, community)
+- `limit` (optional): Maximum number of results (default: 10, max: 50)
+
+**Example**:
+```
+Search for "useState hook" in the learn section
+```
+
+#### `get_doc`
+
+Get a specific documentation page.
+
+**Parameters**:
+- `path` (required): Document path (e.g., "learn/hooks/useState")
+
+**Example**:
+```
+Get the useState documentation
+```
+
+#### `list_sections`
+
+List all available documentation sections.
+
+**Example**:
+```
+What sections are available?
+```
+
+#### `update_docs`
+
+Pull latest documentation from the Git repository.
+
+**Example**:
+```
+Update the React documentation
+```
+
+### Resources
+
+The server exposes documentation as resources with the URI pattern:
+
+```
+react-docs://{section}/{path}
+```
+
+**Examples**:
+- `react-docs://learn` - List all learn section docs
+- `react-docs://learn/hooks/useState` - Get useState documentation
+- `react-docs://reference/react/Component` - Get Component API reference
+
+## Development
+
+### Run in Development Mode
+
+```bash
+npm run dev
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+### Project Structure
+
+```
+reactDocsMcp/
+├── src/
+│   ├── index.ts              # MCP server entry point
+│   ├── docsManager.ts        # Git & file operations
+│   ├── markdownParser.ts     # Markdown parsing
+│   ├── searchEngine.ts       # Search implementation
+│   ├── types.ts              # TypeScript types
+│   └── config.ts             # Configuration
+├── data/
+│   └── react-dev-repo/       # Cloned React docs (auto-created)
+├── dist/                     # Compiled output
+└── TECHNICAL_SPEC.md         # Technical documentation
+```
+
+## How It Works
+
+1. **Initialization**: On first run, clones the official React documentation repository
+2. **Indexing**: Parses all markdown files and builds an in-memory search index
+3. **Search**: Provides keyword-based search with relevance scoring
+4. **Updates**: Can pull latest changes from the repository and re-index
+
+## Troubleshooting
+
+### Server won't start
+
+- Ensure Node.js 18+ is installed
+- Check that the build completed successfully (`npm run build`)
+- Verify the path in your MCP configuration is absolute and correct
+
+### No search results
+
+- The repository may still be cloning (check console output)
+- Try running `update_docs` tool to refresh the index
+
+### Git clone fails
+
+- Check internet connection
+- Verify Git is installed and accessible
+- Check firewall/proxy settings
+
+## Technical Details
+
+For detailed technical information, see [TECHNICAL_SPEC.md](./TECHNICAL_SPEC.md).
+
+## License
+
+MIT
+
+## Contributing
+
+This is a personal project for connecting React documentation to AI coding agents. Feel free to fork and modify for your own use.

package/dist/config.d.ts

@@ -0,0 +1,28 @@
+/**
+ * config.ts
+ * Centralize configuration constants
+ */
+declare const CONFIG: {
+    repo: {
+        url: string;
+        localPath: string;
+        contentPath: string;
+    };
+    search: {
+        defaultLimit: number;
+        maxLimit: number;
+        minScore: number;
+        semanticSearchEnabled: boolean;
+        semanticMinSimilarity: number;
+        hybridKeywordWeight: number;
+        hybridSemanticWeight: number;
+    };
+    server: {
+        name: string;
+        version: string;
+    };
+    sections: readonly ["learn", "reference", "blog", "community"];
+};
+export default CONFIG;
+export type Section = typeof CONFIG.sections[number];
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,QAAA,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;CA2BX,CAAC;AAEF,eAAe,MAAM,CAAC;AACtB,MAAM,MAAM,OAAO,GAAG,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC"}

package/dist/config.js

@@ -0,0 +1,31 @@
+/**
+ * config.ts
+ * Centralize configuration constants
+ */
+const CONFIG = {
+    // Repository settings
+    repo: {
+        url: 'https://github.com/reactjs/react.dev.git',
+        localPath: './data/react-dev-repo',
+        contentPath: 'src/content',
+    },
+    // Search settings
+    search: {
+        defaultLimit: 10,
+        maxLimit: 50,
+        minScore: 0.1,
+        semanticSearchEnabled: true,
+        semanticMinSimilarity: 0.3, // Minimum cosine similarity for semantic results
+        hybridKeywordWeight: 0.3, // Weight for keyword search in hybrid mode
+        hybridSemanticWeight: 0.7, // Weight for semantic search in hybrid mode
+    },
+    // MCP server settings
+    server: {
+        name: 'react-docs-mcp',
+        version: '1.0.0',
+    },
+    // Content sections in the repo
+    sections: ['learn', 'reference', 'blog', 'community'],
+};
+export default CONFIG;
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,GAAG;IACb,sBAAsB;IACtB,IAAI,EAAE;QACJ,GAAG,EAAE,0CAA0C;QAC/C,SAAS,EAAE,uBAAuB;QAClC,WAAW,EAAE,aAAa;KAC3B;IAED,kBAAkB;IAClB,MAAM,EAAE;QACN,YAAY,EAAE,EAAE;QAChB,QAAQ,EAAE,EAAE;QACZ,QAAQ,EAAE,GAAG;QACb,qBAAqB,EAAE,IAAI;QAC3B,qBAAqB,EAAE,GAAG,EAAG,iDAAiD;QAC9E,mBAAmB,EAAE,GAAG,EAAK,2CAA2C;QACxE,oBAAoB,EAAE,GAAG,EAAI,4CAA4C;KAC1E;IAED,sBAAsB;IACtB,MAAM,EAAE;QACN,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,OAAO;KACjB;IAED,+BAA+B;IAC/B,QAAQ,EAAE,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,CAAU;CAC/D,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/docsManager.d.ts

@@ -0,0 +1,57 @@
+/**
+ * docsManager.ts
+ * Handle Git repository operations and file system access
+ */
+import type { RepoStatus } from './types.js';
+export declare class DocsManager {
+    private git;
+    private repoPath;
+    private contentPath;
+    private fileCache;
+    constructor();
+    /**
+     * Initialize the docs manager
+     * Checks if repo exists, clones if needed
+     */
+    initialize(): Promise<void>;
+    /**
+     * Check if repository exists locally
+     */
+    private checkRepoExists;
+    /**
+     * Clone the repository
+     */
+    private cloneRepo;
+    /**
+     * Get repository status
+     */
+    getStatus(): Promise<RepoStatus>;
+    /**
+     * Update repository (git pull)
+     * Returns true if updates were pulled
+     */
+    updateRepo(): Promise<boolean>;
+    /**
+     * Get all markdown files from a section
+     * @param section - Section name (learn, reference, etc.)
+     * @returns Array of file paths relative to content root
+     */
+    getDocsInSection(section: string): Promise<string[]>;
+    /**
+     * Get all markdown files across all sections
+     * @returns Array of file paths relative to content root
+     */
+    getAllDocs(): Promise<string[]>;
+    /**
+     * Read file content
+     * @param relativePath - Path relative to content root
+     * @returns Raw file content
+     */
+    readDoc(relativePath: string): Promise<string>;
+    /**
+     * Check if file exists
+     * @param relativePath - Path relative to content root
+     */
+    docExists(relativePath: string): Promise<boolean>;
+}
+//# sourceMappingURL=docsManager.d.ts.map

package/dist/docsManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docsManager.d.ts","sourceRoot":"","sources":["../src/docsManager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,qBAAa,WAAW;IACtB,OAAO,CAAC,GAAG,CAAY;IACvB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,SAAS,CAAoC;;IAQrD;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAYjC;;OAEG;YACW,eAAe;IAS7B;;OAEG;YACW,SAAS;IAevB;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,UAAU,CAAC;IAsBtC;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IAgCpC;;;;OAIG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA4B1D;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAgBrC;;;;OAIG;IACG,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAYpD;;;OAGG;IACG,SAAS,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAUxD"}

package/dist/docsManager.js

@@ -0,0 +1,185 @@
+/**
+ * docsManager.ts
+ * Handle Git repository operations and file system access
+ */
+import { simpleGit } from 'simple-git';
+import { promises as fs } from 'fs';
+import path from 'path';
+import fg from 'fast-glob';
+import CONFIG from './config.js';
+export class DocsManager {
+    git;
+    repoPath;
+    contentPath;
+    fileCache = new Map();
+    constructor() {
+        this.repoPath = path.resolve(CONFIG.repo.localPath);
+        this.contentPath = path.join(this.repoPath, CONFIG.repo.contentPath);
+        this.git = simpleGit();
+    }
+    /**
+     * Initialize the docs manager
+     * Checks if repo exists, clones if needed
+     */
+    async initialize() {
+        const repoExists = await this.checkRepoExists();
+        if (!repoExists) {
+            console.log('Cloning React documentation repository...');
+            await this.cloneRepo();
+            console.log('Repository cloned successfully');
+        }
+        else {
+            console.log('Repository already exists');
+        }
+    }
+    /**
+     * Check if repository exists locally
+     */
+    async checkRepoExists() {
+        try {
+            await fs.access(path.join(this.repoPath, '.git'));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Clone the repository
+     */
+    async cloneRepo() {
+        try {
+            // Ensure parent directory exists
+            await fs.mkdir(path.dirname(this.repoPath), { recursive: true });
+            await this.git.clone(CONFIG.repo.url, this.repoPath, {
+                '--depth': 1, // Shallow clone for faster download
+            });
+        }
+        catch (error) {
+            throw new Error(`Failed to clone repository: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Get repository status
+     */
+    async getStatus() {
+        const isCloned = await this.checkRepoExists();
+        if (!isCloned) {
+            return { isCloned: false };
+        }
+        try {
+            const git = simpleGit(this.repoPath);
+            const log = await git.log({ maxCount: 1 });
+            return {
+                isCloned: true,
+                currentCommit: log.latest?.hash,
+                lastUpdated: log.latest?.date ? new Date(log.latest.date) : undefined,
+            };
+        }
+        catch (error) {
+            console.error('Failed to get repo status:', error);
+            return { isCloned: true };
+        }
+    }
+    /**
+     * Update repository (git pull)
+     * Returns true if updates were pulled
+     */
+    async updateRepo() {
+        const isCloned = await this.checkRepoExists();
+        if (!isCloned) {
+            throw new Error('Repository not cloned. Call initialize() first.');
+        }
+        try {
+            const git = simpleGit(this.repoPath);
+            const beforeHash = await git.revparse(['HEAD']);
+            await git.pull();
+            const afterHash = await git.revparse(['HEAD']);
+            const hasUpdates = beforeHash !== afterHash;
+            if (hasUpdates) {
+                // Clear file cache when repo is updated
+                this.fileCache.clear();
+                console.log('Repository updated successfully');
+            }
+            else {
+                console.log('Repository already up to date');
+            }
+            return hasUpdates;
+        }
+        catch (error) {
+            throw new Error(`Failed to update repository: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Get all markdown files from a section
+     * @param section - Section name (learn, reference, etc.)
+     * @returns Array of file paths relative to content root
+     */
+    async getDocsInSection(section) {
+        const cacheKey = `section:${section}`;
+        if (this.fileCache.has(cacheKey)) {
+            return this.fileCache.get(cacheKey);
+        }
+        const sectionPath = path.join(this.contentPath, section);
+        try {
+            await fs.access(sectionPath);
+        }
+        catch {
+            // Section doesn't exist
+            return [];
+        }
+        const files = await fg('**/*.md', {
+            cwd: sectionPath,
+            absolute: false,
+        });
+        // Convert to paths relative to content root
+        const relativePaths = files.map(file => `${section}/${file}`);
+        this.fileCache.set(cacheKey, relativePaths);
+        return relativePaths;
+    }
+    /**
+     * Get all markdown files across all sections
+     * @returns Array of file paths relative to content root
+     */
+    async getAllDocs() {
+        const cacheKey = 'all';
+        if (this.fileCache.has(cacheKey)) {
+            return this.fileCache.get(cacheKey);
+        }
+        const files = await fg('**/*.md', {
+            cwd: this.contentPath,
+            absolute: false,
+        });
+        this.fileCache.set(cacheKey, files);
+        return files;
+    }
+    /**
+     * Read file content
+     * @param relativePath - Path relative to content root
+     * @returns Raw file content
+     */
+    async readDoc(relativePath) {
+        const fullPath = path.join(this.contentPath, relativePath);
+        try {
+            return await fs.readFile(fullPath, 'utf-8');
+        }
+        catch (error) {
+            throw new Error(`Failed to read document at ${relativePath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Check if file exists
+     * @param relativePath - Path relative to content root
+     */
+    async docExists(relativePath) {
+        const fullPath = path.join(this.contentPath, relativePath);
+        try {
+            await fs.access(fullPath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=docsManager.js.map

package/dist/docsManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docsManager.js","sourceRoot":"","sources":["../src/docsManager.ts"],"names":[],"mappings":"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"}

package/dist/embeddingService.d.ts

@@ -0,0 +1,52 @@
+/**
+ * embeddingService.ts
+ * Generate embeddings using transformers.js for semantic search
+ */
+/**
+ * Embedding service using all-MiniLM-L6-v2 model
+ * This is a lightweight model (23MB) optimized for semantic similarity
+ */
+export declare class EmbeddingService {
+    private pipeline;
+    private initialized;
+    private modelName;
+    /**
+     * Initialize the embedding pipeline
+     * Downloads model on first run (~23MB)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Generate embedding for a text
+     * @param text - Text to embed
+     * @returns Vector embedding (384 dimensions for all-MiniLM-L6-v2)
+     */
+    generateEmbedding(text: string): Promise<number[]>;
+    /**
+     * Generate embeddings for multiple texts (batch processing)
+     * @param texts - Array of texts to embed
+     * @returns Array of vector embeddings
+     */
+    generateEmbeddings(texts: string[]): Promise<number[][]>;
+    /**
+     * Calculate cosine similarity between two vectors
+     * @param a - First vector
+     * @param b - Second vector
+     * @returns Similarity score (0-1, higher is more similar)
+     */
+    cosineSimilarity(a: number[], b: number[]): number;
+    /**
+     * Find most similar vectors to a query vector
+     * @param queryEmbedding - Query vector
+     * @param docEmbeddings - Array of document vectors with metadata
+     * @param topK - Number of results to return
+     * @returns Array of {index, similarity} sorted by similarity desc
+     */
+    findMostSimilar(queryEmbedding: number[], docEmbeddings: Array<{
+        embedding: number[];
+        index: number;
+    }>, topK: number): Array<{
+        index: number;
+        similarity: number;
+    }>;
+}
+//# sourceMappingURL=embeddingService.d.ts.map

package/dist/embeddingService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embeddingService.d.ts","sourceRoot":"","sources":["../src/embeddingService.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH;;;GAGG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,SAAS,CAAqC;IAEtD;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAejC;;;;OAIG;IACG,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAuBxD;;;;OAIG;IACG,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IAW9D;;;;;OAKG;IACH,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM;IAsBlD;;;;;;OAMG;IACH,eAAe,CACb,cAAc,EAAE,MAAM,EAAE,EACxB,aAAa,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,EAC5D,IAAI,EAAE,MAAM,GACX,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CAWhD"}