jalezi/npm-documentation-mcp-server

NPM Documentation MCP Server

A Model Context Protocol (MCP) server that provides access to npm package documentation and information directly within VS Code and other MCP-compatible environments.

Features

• Search NPM Packages: Find packages by name or keywords
• Package Information: Get detailed info including dependencies, maintainers, and metadata
• README Documentation: Retrieve full README documentation for any package
• Version Management: List all available versions of a package
• Repository Discovery: Find and analyze GitHub repositories linked to packages
• Documentation Link Discovery: Automatically discover official documentation sites
• Repository Exploration: Explore GitHub repositories to find documentation files
• Content Fetching: Fetch and analyze content from documentation URLs
• Real-time Data: Always fetches the latest information from npm registry and GitHub

Installation

1. Clone or create the project:

mkdir npm-documentation-mcp-server
cd npm-documentation-mcp-server

2. Create the directory structure:

mkdir src

3. Copy the provided files:

   • Save the TypeScript code as src/index.ts
   • Save the package.json in the root directory
   • Save the tsconfig.json in the root directory

4. Install dependencies:

npm install

5. Build the project:

npm run build

VS Code Configuration

This project includes a .vscode/mcp.json file for easy VS Code integration. To use this MCP server with VS Code:

Prerequisites

• VS Code: Version 1.99 or later (required for MCP support)
• Enable MCP Support: Add to your VS Code settings.json:

  {
    "chat.mcp.enabled": true,
    "chat.agent.enabled": true
  }
  

Quick Setup (Workspace)

1. Build the project:

   pnpm run build
   

2. Restart VS Code or reload the window (Cmd+Shift+P → "Developer: Reload Window")

The server will be automatically configured for this workspace using the included .vscode/mcp.json file.

Alternative: User Settings (Global)

Add to your VS Code user settings.json:

{
  "mcp": {
    "servers": {
      "npm-documentation": {
        "type": "stdio",
        "command": "node",
        "args": ["/full/path/to/your/npm-documentation-mcp-server/dist/index.js"],
        "env": {}
      }
    }
  }
}

Alternative: Global Installation

npm link

Then use in VS Code settings:

{
  "mcp": {
    "servers": {
      "npm-documentation": {
        "type": "stdio",
        "command": "npm-documentation-mcp-server",
        "args": [],
        "env": {}
      }
    }
  }
}

Available Tools

1. search_npm_packages

Search for npm packages by name or keywords.

Parameters:

• query (required): Search query for npm packages
• limit (optional): Number of results (default: 10, max: 50)

Example usage:

Search for React components: "react component"
Find testing libraries: "testing jest"

2. get_package_info

Get detailed information about a specific npm package.

Parameters:

• packageName (required): Name of the npm package
• version (optional): Specific version to fetch

Example usage:

Get info for React: "react"
Get specific version: "lodash@4.17.21"

3. get_package_readme

Retrieve the README documentation for an npm package.

Parameters:

• packageName (required): Name of the npm package
• version (optional): Specific version to fetch README for

Example usage:

Get React README: "react"
Get specific version README: "express@4.18.0"

4. get_package_versions

List all available versions of an npm package.

Parameters:

• packageName (required): Name of the npm package

Example usage:

List React versions: "react"
Check available TypeScript versions: "typescript"

5. find_documentation_links

Find repository and documentation links for an npm package.

Parameters:

• packageName (required): Name of the npm package

Example usage:

Find React documentation: "react"
Discover Express.js docs: "express"

What it provides:

• GitHub repository information (stars, forks, issues, topics)
• Official documentation sites
• API documentation links
• GitHub Wiki and Pages
• Repository statistics and metadata

6. explore_repository

Explore a GitHub repository to find documentation files and structure.

Parameters:

• repositoryUrl (required): GitHub repository URL to explore
• packageName (optional): Name of the package for context

Example usage:

Explore React repo: "https://github.com/facebook/react"
Analyze Express repo: "https://github.com/expressjs/express"

What it finds:

• README files in repository root and docs directory
• Documentation markdown files
• API documentation files
• Changelog and contributing guidelines
• File content previews with relevance scoring

7. fetch_documentation_content

Fetch and analyze content from documentation URLs.

Parameters:

• urls (required): Array of URLs to fetch content from (max 5)
• packageName (optional): Name of the package for context

Example usage:

Fetch multiple docs: ["https://reactjs.org/docs", "https://react.dev/learn"]
Get API docs: ["https://expressjs.com/en/4x/api.html"]

Features:

• Fetches content from web pages
• Extracts readable text from HTML
• Handles various content types
• Provides content previews with length limits

Development

Running in Development Mode

npm run dev

Building for Production

npm run build
npm start

Project Structure

npm-documentation-mcp-server/
├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript (after build)
├── package.json          # Project dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file

How It Works

The enhanced server provides comprehensive npm package documentation discovery through multiple data sources:

NPM Registry Integration

• Searches packages using the official npm search endpoint
• Fetches package metadata, dependencies, and README content
• Retrieves version information and maintainer details

GitHub Repository Analysis

• Automatically discovers and analyzes linked GitHub repositories
• Fetches repository statistics (stars, forks, issues, topics)
• Explores repository structure to find documentation files
• Provides intelligent file relevance scoring

Documentation Discovery

• Scans for official documentation sites using common URL patterns
• Discovers API documentation, guides, and tutorials
• Identifies GitHub Wiki and Pages when available
• Tests discovered URLs for accessibility

Content Exploration

• Fetches and analyzes content from documentation URLs
• Extracts readable text from HTML pages
• Provides content previews with intelligent truncation
• Handles various content types (HTML, Markdown, plain text)

All data is fetched in real-time, ensuring you always get the most current information about npm packages and their documentation ecosystem.

Troubleshooting

Common Issues

1. "Command not found" error: Make sure the path in your MCP configuration is correct and points to the built dist/index.js file.

2. Network errors: The server requires internet access to fetch data from the npm registry.

3. Build errors: Ensure you have Node.js 18+ and TypeScript installed.

Debug Mode

You can add debug logging by modifying the error handling in the source code or checking the MCP client logs.

Example Workflows

1. Complete Package Analysis

# 1. Search for packages
search_npm_packages: "react testing"

# 2. Get detailed info for a specific package
get_package_info: "react-testing-library"

# 3. Find all documentation sources
find_documentation_links: "react-testing-library"

# 4. Explore the GitHub repository
explore_repository: "https://github.com/testing-library/react-testing-library"

# 5. Fetch specific documentation content
fetch_documentation_content: ["https://testing-library.com/docs/react-testing-library/intro"]

2. Comprehensive Documentation Discovery

# Start with any package name
find_documentation_links: "express"

# This will give you:
# - Repository URL and statistics
# - Official documentation sites
# - API documentation links
# - Community resources

# Then explore the repository for more files
explore_repository: "https://github.com/expressjs/express"

# Finally fetch content from discovered URLs
fetch_documentation_content: ["https://expressjs.com/en/api.html", "https://expressjs.com/en/guide/"]

3. Quick Documentation Access

# Get README and find docs in one workflow
get_package_readme: "lodash"
find_documentation_links: "lodash"

Advanced Configuration

GitHub API Rate Limiting

The server makes requests to GitHub's API for repository information. While it doesn't require authentication, you can optionally add a GitHub token to increase rate limits:

{
  "mcp": {
    "servers": {
      "npm-documentation": {
        "type": "stdio",
        "command": "node",
        "args": ["/path/to/npm-documentation-mcp-server/dist/index.js"],
        "env": {
          "GITHUB_TOKEN": "your_github_token_here"
        }
      }
    }
  }
}

Custom Timeouts

The server includes reasonable timeouts for web requests, but you can modify them in the source code:

// In fetchWebContent method
timeout: 10000; // 10 seconds

// In GitHub API calls
timeout: 5000; // 5 seconds for doc URL discovery

API Reference

Response Format

All tools return structured text responses that include:

• Formatted headers for easy scanning
• Clickable URLs for direct access
• Metadata like stars, forks, and update dates
• Content previews with intelligent truncation
• Suggested next steps for further exploration

Error Handling

The server provides clear error messages for common scenarios:

• Package not found: Clear indication when packages don't exist
• Network timeouts: Graceful handling of slow responses
• Invalid URLs: Validation and normalization of repository URLs
• Rate limiting: Informative messages about API limits

Content Types Supported

• Markdown files (.md, .markdown)
• Plain text documentation
• HTML pages with text extraction
• JSON responses from APIs
• Repository files (README, CHANGELOG, CONTRIBUTING, etc.)

Security Considerations

Safe URL Handling

• Only fetches from HTTPS URLs
• Validates GitHub repository URLs
• Implements request timeouts to prevent hanging
• Limits content size to prevent memory issues

No Authentication Storage

• Does not store or log any authentication tokens
• GitHub API calls are read-only
• No persistent data storage

Rate Limiting Awareness

• Respects GitHub API rate limits
• Implements reasonable delays between requests
• Provides clear error messages when limits are reached

Contributing

Feel free to extend this server with additional features such as:

• Package vulnerability checking using npm audit data
• Download statistics from npm registry
• Dependency tree analysis with visualization
• Package comparison tools for feature comparison
• BitBucket and GitLab repository support
• Documentation quality scoring
• Automated testing documentation discovery
• Integration with other documentation platforms (GitBook, Notion, etc.)

Potential Enhancements

• AI-powered documentation summarization
• Documentation freshness analysis
• Community resource discovery (tutorials, videos, courses)
• Package ecosystem mapping
• Alternative package suggestions

License

MIT License - feel free to use and modify as needed.