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