MCP Node Documentation

A Model Context Protocol (MCP) server that retrieves documentation for any npm package by automatically discovering its GitHub repository and returning its README.md.

The server is built using the official @modelcontextprotocol/server SDK and communicates over STDIO, making it compatible with MCP clients such as Claude Desktop, the MCP Inspector, and other MCP-compatible applications.

Features

• Fetches package information directly from the npm registry.

• Automatically detects the GitHub repository associated with an npm package.

• Downloads the project's README from GitHub.

• Supports repositories using either:

  • main

  • master

• Supports common README filename variations:

  • README.md

  • Readme.md

  • readme.md

• Uses request timeouts to avoid hanging requests.

• Implements clean separation between:

  • MCP Server

  • Service Layer

  • HTTP Layer

• Fully written in TypeScript.

• Compatible with MCP 2.x.

How It Works

          User / MCP Client
                  │
                  ▼
        MCP Tool Invocation
                  │
                  ▼
        npm-package-documentation
                  │
                  ▼
       Fetch npm Registry Metadata
                  │
                  ▼
      Extract GitHub Repository URL
                  │
                  ▼
        Download README.md
                  │
                  ▼
        Return README as Response

Project Structure

mcp-node-documentation
│
├── src
│   ├── index.ts
│   │
│   └── service
│       ├── data.model.ts
│       ├── fetch.api.ts
│       ├── service.ts
│       └── service.implementation.ts
│
├── package.json
├── tsconfig.json
├── .gitignore
└── README.md

Folder Explanation

src/index.ts

Entry point of the application.

Responsibilities:

• Creates the MCP Server.

• Registers the tool.

• Connects using StdioServerTransport.

• Handles tool requests.

• Returns documentation to the MCP client.

Registered Tool:

npm-package-documentation

Input:

{
    "packageName": "express"
}

Output:

Contents of README.md

Related MCP server: NPM Context Agent MCP

src/service/service.ts

Defines the service interface.

interface Service {
    getRepoInfo(packageName: string): Promise<RepoInfo>;
    getDocumentation(user: string, repo: string): Promise<DocumentationResponse>;
}

This abstraction allows multiple implementations in the future.

src/service/service.implementation.ts

Contains all business logic.

Responsibilities:

1. Fetch npm package metadata

Example:

https://registry.npmjs.org/express

Extracts

{
    "repository": {
        "url": "git+https://github.com/expressjs/express.git"
    }
}

Converts it into

user = expressjs
repo = express

2. Fetch GitHub README

It searches multiple possible locations.

Examples:

main/README.md
master/README.md
main/readme.md
master/readme.md
main/Readme.md
master/Readme.md

The first successful request is returned using

Promise.any(...)

src/service/fetch.api.ts

Wrapper around the native fetch() API.

Features:

• Timeout support

• AbortController

• Error handling

• Automatic cleanup

Instead of repeatedly writing

fetch(...)

the project uses

fetchApi.fetch(...)

which provides consistent behavior.

src/service/data.model.ts

Contains project models.

export interface RepoInfo {
    user: string;
    repo: string;
}

and

export type DocumentationResponse = {
    CONTENT: string;
}

Tool Definition

Tool Name

npm-package-documentation

Input Schema

{
    "packageName": "string"
}

Example

{
    "packageName": "react"
}

Response

Entire README.md content

Request Flow

User

↓

MCP Tool

↓

getRepoInfo()

↓

npm Registry API

↓

GitHub Repository

↓

getDocumentation()

↓

raw.githubusercontent.com

↓

README.md

↓

MCP Response

Installation

Clone the repository.

git clone https://github.com/<your-username>/mcp-node-documentation.git

Move into the project.

cd mcp-node-documentation

Install dependencies.

npm install

Build

npm run build

Compiled JavaScript will be generated inside

dist/

Development

Run in watch mode.

npm run dev

Production

npm start

Run MCP Inspector

npm run local

This launches the official MCP Inspector.

You can invoke the tool directly from the Inspector UI.

Example Tool Call

Input

{
    "packageName": "express"
}

Processing

↓

Fetch npm registry

↓

Extract repository

↓

Fetch README

↓

Return documentation

Output

# Express

Fast, unopinionated, minimalist web framework...

APIs Used

npm Registry

https://registry.npmjs.org/<package-name>

Example

https://registry.npmjs.org/react

Used for discovering the GitHub repository.

GitHub Raw Content

https://raw.githubusercontent.com/<user>/<repo>/<branch>/README.md

Example

https://raw.githubusercontent.com/facebook/react/main/README.md

Used for retrieving documentation.

Error Handling

The project gracefully handles:

• Invalid package names

• Missing repositories

• Non-GitHub repositories

• Missing README files

• Network failures

• Timeout errors

• Invalid GitHub URLs

Errors are returned as plain text responses to the MCP client.

Dependencies

Runtime

Development

Design Decisions

The project follows a layered architecture.

MCP Server

↓

Service Layer

↓

HTTP Layer

↓

External APIs

Benefits:

• Easy to maintain

• Easy to test

• Easy to extend

• Separation of concerns

• Reusable HTTP logic

Future Improvements

Potential enhancements include:

• Support GitLab repositories.

• Support Bitbucket repositories.

• Cache README responses.

• Add configurable request timeouts.

• Return additional package metadata (version, description, homepage, author).

• Support documentation files other than README (e.g., docs/, CONTRIBUTING.md, CHANGELOG.md).

• Support branch detection via the GitHub API instead of assuming main or master.

• Add unit and integration tests.

• Add logging with configurable log levels.

• Publish the MCP server as an npm package.

• Containerize with Docker.

• Add CI/CD workflows using GitHub Actions.

Requirements

• Node.js 20+

• npm

• TypeScript

License

This project is licensed under the ISC License.

Author

Developed as a simple MCP server that demonstrates how to integrate the npm Registry API with GitHub's raw content service to provide package documentation on demand.