https://github.com/bsmi021/mcp-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.
https://github.com/bsmi021/mcp-npm_docs-server
claude docs modelcontextprotocol mpc npm npm-package
Last synced: 8 months ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/bsmi021/mcp-npm_docs-server
- Owner: bsmi021
- License: mit
- Created: 2025-03-30T13:43:47.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-04-03T21:42:25.000Z (8 months ago)
- Last Synced: 2025-04-03T22:30:56.975Z (8 months ago)
- Topics: claude, docs, modelcontextprotocol, mpc, npm, npm-package
- Language: TypeScript
- Homepage:
- Size: 60.5 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-mcp-servers - **mcp-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. `typescript` `claude` `docs` `modelcontextprotocol` `mpc` `npm install bsmi021/mcp-npm_docs-server` (📚 Documentation)
README
# 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
npm-docs-server
getNpmPackageDocs
{
"packageName": "lodash",
"forceFresh": false
}
```
## 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).