McpDocServer

# MCP Server [English Documentation](README_EN.md) A development documentation server based on the MCP protocol, designed for various development framework documentation. Provides features such as multi-threaded document crawling, local document loading, keyword search, and document details retrieval. ## Core Functionality Demonstration ### 1. Document Crawling Demonstration  *Complete document crawling process from configuration to execution of `npm run crawl`* ### 2. MCP Server Call Demonstration  *Process of querying API in Cursor and obtaining accurate document results* ## Solving Cursor Hallucinations When using Cursor for various framework developments, AI often encounters inaccurate understanding of framework APIs, leading to "hallucinations": - **Accuracy Issues**: AI may recommend non-existent or outdated framework APIs and components - **Version Confusion**: Mixing different versions of API documentation, causing code to not run normally - **Parameter Errors**: Inaccurate understanding of method parameters, especially for framework-specific features - **Compatibility Misjudgment**: Unable to accurately judge the compatibility of an API in different environments or platforms This MCP server effectively solves the above problems by providing precise document retrieval capabilities: - **Real-time Accurate Query**: Directly obtain the latest accurate API information from official document sources - **Context Association**: Associate and display related API and component document references, providing complete references - **Parameter Precise Matching**: Provide complete method signatures and parameter lists, eliminating parameter errors - **Cross-platform Compatibility Marking**: Clearly mark API compatibility in different platforms - **Example Code**: Provide official example code to ensure correct usage By integrating this MCP server, you can significantly improve Cursor's accuracy and efficiency in various framework development processes, avoiding "hallucinations" that bring development obstacles. ## Features - Supports loading framework document data from local JSON files - Provides powerful document search functionality - Provides document details query - Automatically identifies available document sources - Supports targeted queries for specific document sources - Supports crawling external documents and automatically converting them to locally available formats - Supports reloading documents (triggered by searching "reload") ## Directory Structure ``` / ├── server.js # Server entry file ├── docs/ # Document data directory │ ├── taro-docs.json # Taro framework documentation │ └── taroify-docs.json # Taroify component library documentation ├── scripts/ # Script directory │ └── crawl.js # Document crawling script ├── tests/ # Test directory │ └── mcp.test.js # MCP test script ├── config/ # Configuration file directory │ └── doc-sources.js # Document source configuration └── package.json # Project configuration ``` ### Installation and Running If you have already installed Chrome locally and want puppeteer to use your existing version, set the PUPPETEER_SKIP_DOWNLOAD environment variable: macOS/Linux: ```bash export PUPPETEER_SKIP_DOWNLOAD=true npm install ``` Windows (Command Prompt): ```bash set PUPPETEER_SKIP_DOWNLOAD=true npm install ``` Windows (PowerShell): ```bash $env:PUPPETEER_SKIP_DOWNLOAD = $true npm install ``` 2. Crawling Document Data The crawler is used to obtain framework document data and is an important step before using the server. You need to create a crawler configuration file and then run the crawler script. ### Creating Crawler Configuration Create a `doc-sources.js` file in the `config` directory, referring to the following format: ```javascript // config/doc-sources.js // Document source configuration export const docSources = [ { // Document source name - will be used as the source parameter during search name: "taro", // Document website base URL url: "https://docs.taro.zone/docs", // Include patterns - specify the URL paths to crawl (empty array means all pages) includePatterns: [ ], // Exclude patterns - specify the URL paths not to crawl (support regular expressions) excludePatterns: [ /\d\.x/, // Exclude version number pages /apis/ // Exclude API pages ] }, { name: "taroify", url: "https://taroify.github.io/taroify.com/introduce/", includePatterns: [ "/components/", // All component pages "/components/*/", // Component sub-pages "/components/*/*/" // Component sub-sub-pages ], excludePatterns: [] }, { name: "jquery", url: "https://www.jquery123.com/", includePatterns: [], // Empty array means crawl all pages excludePatterns: [ /version/ // Exclude version-related pages ] } ]; // Crawler global configuration export const crawlerConfig = { // Number of concurrent crawling threads maxConcurrency: 40, // Page load timeout (milliseconds) pageLoadTimeout: 30000, // Content load timeout (milliseconds) contentLoadTimeout: 5000, // Whether to display the browser window (false for headless mode) headless: false, // Number of retries maxRetries: 3, // Retry interval (milliseconds) retryDelay: 2000, // Request interval (milliseconds) requestDelay: 1000 }; ``` ### Running the Crawler After configuration, execute the following command to start the crawler: ```bash npm run crawl ``` The crawler will automatically crawl the specified document website according to the configuration and save the results as JSON files that meet the MCP server requirements. ### Crawler Output Example After the crawler is completed, a JSON file of the following format will be generated in the `docs` directory: ```javascript { "source": { "name": "taro", "url": "https://docs.taro.zone/docs" }, "lastUpdated": "2024-05-20T12:00:00.000Z", "pages": { "https://docs.taro.zone/docs/components-desc": { "title": "Component Library Description | Taro Documentation", "content": "Page content...", "lastCrawled": "2024-05-20T12:00:00.000Z" }, "https://docs.taro.zone/docs/components/viewcontainer/view": { "title": "View | Taro Documentation", "content": "View component is a container component...", "lastCrawled": "2024-05-20T12:00:00.000Z" } // ... More pages } } ``` ### Customizing the Crawler If you need to customize the crawler behavior, you can modify the `scripts/crawl.js` file. You can add specific website parsing logic, custom content processing, or enhanced crawling capabilities. 3. Starting the MCP Server ```bash npm start ``` After starting, the server will detect and load document files in the docs directory and provide interface services through the MCP protocol. The server will output the loaded document source information and page count. 4. Running Tests ```bash npm test ``` Execute the test script to verify the basic functionality and interface normal operation of the MCP server. ## Document Format Document files should be JSON files containing the following structure: ```javascript { "source": { "name": "taro", "url": "https://docs.taro.zone/docs" }, "lastUpdated": "2024-03-27T12:00:00.000Z", "pages": { "https://docs.taro.zone/docs/components-desc": { "title": "Component Library Description | Taro Documentation", "content": "Page content..." }, // More pages... } } ``` Document loading process: 1. The server will automatically detect and load JSON files in the `docs` directory when started 2. If no document is found in the project directory, it will try to load from the current working directory 3. The page ID defaults to using the URL as the key, no need to specify the url field additionally 4. All source names will be converted to lowercase to ensure consistency ## Crawler Functionality The system has a built-in crawler that supports crawling content from various framework official document sites and converting it into locally available document formats. Crawler features include: 1. **Multi-site Support**: Supports document websites of any framework and library, fully configurable 2. **Selective Crawling**: Can configure include and exclude patterns to precisely control the content to be crawled 3. **Intelligent Content Extraction**: Automatically identifies document page titles, content, and structure 4. **Multi-threaded Crawling**: Supports high-concurrency crawling to improve efficiency 5. **Automatic Conversion**: Converts crawled content into standard document JSON format 6. **Fault Tolerance Mechanism**: Provides timeout handling and retry mechanism to enhance stability ## MCP Tools The server provides the following MCP tools: 1. `search_docs` - Search documents - Parameters: - `query`: Search keyword (string, required) - `source`: Document source name (string, optional) - `limit`: Maximum result count (number, optional, default 10) - Special features: - When query is "reload", it will trigger reloading documents 2. `get_doc_detail` - Get document details - Parameters: - `id`: Document ID (string, required) - `source`: Document source name (string, optional) ## Usage Examples ```javascript // Search documents const searchRequest = { jsonrpc: "2.0", id: "search1", method: "tools/call", params: { name: "search_docs", arguments: { query: "component", source: "taro", limit: 5 } } }; // Get document details const detailRequest = { jsonrpc: "2.0", id: "detail1", method: "tools/call", params: { name: "get_doc_detail", arguments: { id: "https://docs.taro.zone/docs/components-desc", source: "taro" } } }; // Reload documents const reloadRequest = { jsonrpc: "2.0", id: "reload1", method: "tools/call", params: { name: "search_docs", arguments: { query: "reload" } } }; ``` ## Configuring Cursor To use this server in Cursor, add the following configuration to `mcp.json`: ```json { "mcpServers": { "Documentation MCP Server": { "command": "node", "args": ["/absolute/path/server.js"], "env": { "NODE_ENV": "development" } } } } ``` > Note: Make sure to use the complete absolute path of the server file, not a relative path. The server will output the configuration example applicable to Cursor when started. ## Testing The project contains automated tests that can be run with the following command: ```bash npm test ``` The test will check the server's basic functionality: - Initialize MCP Server - Call search tools - Call document details tools ## Future Plans The project is under continuous development, and the following are the features we plan to add: 1. **Local Document Loading** - Add direct loading and parsing of local document files, no need to rely on network resources 2. **Internationalization Support** - Add support for multi-language documents If you have feature suggestions or find issues, feel free to submit an issue or pull request.