mcp-npm_docs-server

# NPM Documentation MCP Server An MCP server that provides a tool to fetch metadata and documentation (including README content) for NPM packages, using a local cache to improve performance. ## Features - Fetches package metadata and README content using the [npms.io API](https://api.npms.io/). - Caches results locally using SQLite (`better-sqlite3`). - Provides the `getNpmPackageDocs` MCP tool. - Follows the standard MCP server structure. ## Project Structure - `/src`: Contains all source code. - `/config`: Configuration management (`ConfigurationManager`). - `/services`: Core logic (`NpmDocService`, `CacheService`). - `/tools`: MCP tool definition (`npmDocsTool.ts`, `npmDocsToolParams.ts`). - `/types`: TypeScript interfaces and custom errors (`npmDocsTypes.ts`). - `/utils`: Shared utility functions (`logger.ts`, `errors.ts`). - `createServer.ts`: Server instance creation and tool registration. - `server.ts`: Main application entry point. - `/dist`: Compiled JavaScript output (generated by `npm run build`). Contains the default cache DB file (`npm-docs-cache.db`). - `package.json`: Project metadata and dependencies. - `tsconfig.json`: TypeScript compiler options. - `.eslintrc.json`: ESLint configuration. - `.prettierrc.json`: Prettier configuration. - `.gitignore`: Git ignore rules. ## Installation & Setup 1. **Clone the repository (if applicable).** 2. **Install Dependencies:** ```bash npm install ``` 3. **Build the Server:** ```bash npm run build ``` This compiles the TypeScript code into the `dist/` directory. ## Configuration The server can be configured using environment variables: - `NPM_CACHE_TTL`: Cache Time-To-Live in seconds. (Default: `86400` - 24 hours) - `NPM_CACHE_DB_PATH`: Path to the SQLite database file. (Default: `./dist/npm-docs-cache.db` - relative to the project root after build). If set, this overrides the default. Can be an absolute path or relative to the current working directory where the server is started. - `LOG_LEVEL`: Set to `debug` for verbose logging. (Default: `info`) *Note: The `NPM_REGISTRY_URL` config variable exists but is currently ignored as the server uses the `npms.io` API.* ## Running the Server You can run the compiled server directly using Node: ```bash node dist/server.js ``` For development, use the `dev` script for auto-reloading: ```bash npm run dev ``` ## MCP Integration To use this server with an MCP client (like Cline), add its configuration to your MCP settings file (e.g., `cline_mcp_settings.json`): ```json { "mcpServers": { // ... other servers "npm-docs-server": { "command": "node", "args": [ "/path/to/mcp-npm_docs-server/dist/server.js" // <-- IMPORTANT: Use the absolute path to the compiled server.js ], "env": { // Optional: Set environment variables here if needed // "NPM_CACHE_TTL": "3600", // "NPM_CACHE_DB_PATH": "/path/to/your/cache.db", // "LOG_LEVEL": "debug" }, "disabled": false, // Ensure it's enabled "autoApprove": [ "getNpmPackageDocs" // Optional: Auto-approve the tool ] } // ... other servers } } ``` **Replace `/path/to/mcp-npm_docs-server` with the actual absolute path to this project directory on your system.** ## Provided MCP Tool ### `getNpmPackageDocs` Retrieves documentation and metadata for a specified NPM package. **Parameters:** - `packageName` (string, **required**): The exact name of the NPM package (e.g., 'react', 'axios', '@azure/storage-blob'). Case-sensitive. - `forceFresh` (boolean, optional, default: `false`): If `true`, bypasses the local cache and fetches fresh data from the npms.io API. **Returns:** A JSON object conforming to the `NpmDocumentation` interface, including: - `name` - `version` - `description` - `homepage` (if available) - `repository` (URL, if available) - `author` (name, if available) - `license` (if available) - `keywords` (if available) - `dependencies` - `devDependencies` - `readmeContent` (string containing README markdown, if available via npms.io) **Example Usage (MCP Tool Call):** ```xml <use_mcp_tool> <server_name>npm-docs-server</server_name> <tool_name>getNpmPackageDocs</tool_name> <arguments> { "packageName": "lodash", "forceFresh": false } </arguments> </use_mcp_tool> ``` ## Linting and Formatting - **Lint:** `npm run lint` - **Format:** `npm run format` Code will be automatically linted and formatted on commit via Husky and lint-staged (if Husky is installed).