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