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.
- 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:

    npm install
    

3. Build the Server:

    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:

node dist/server.js

For development, use the dev script for auto-reloading:

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):

{
  "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):

<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).