Skip to main content
Glama
xvantz

ts-docs-mcp

by xvantz
OverviewSchemaRelated ServersScoreDiscussions
TypeScript

ts-docs-mcp

An MCP server that gives AI coding agents accurate, version-aware API documentation for any npm package — straight from the source.

⚡ npx ts-docs-mcp — works with Cursor, Claude Code, VS Code Copilot, and any MCP-compatible client.

The Problem

When you ask an AI coding agent (Claude Code, Cursor, Copilot) to write code using an npm package, the model relies on its training data — which is often months or years out of date.

The result:

// ❌ Model hallucinates — Express 4 syntax, but you have Express 5 installed
import bodyParser from 'body-parser';
app.use(bodyParser.json());

// ❌ Wrong API — Zod v3 pattern, but Zod v4 changed the API
const schema = z.object({ name: z.string() });
schema.parse(data); // Zod v4 requires schema.parse({...}) with options

Models know about libraries, but they don't know which version you have installed or what the current API looks like.

Related MCP server: @particle-academy/docs-mcp

The Solution

ts-docs-mcp provides documentation sourced from the actual package source code — not training data.

The pipeline:

npm registry → GitHub .ts (JSDoc) → npm tarball (.d.ts) → DefinitelyTyped (@types/)

  1. Resolves the exact version from the npm registry

  2. Reads TypeScript source from GitHub, including JSDoc, @param, @returns

  3. Follows re-exports to find actual declarations (BFS, parallel fetches)

  4. Falls back to .d.ts from the npm tarball if GitHub source is insufficient

  5. Falls back to DefinitelyTyped for JS-only packages (express, etc.)

  6. Returns clean Markdown — full signatures, parameters, deprecation notices, examples

Before vs After

Package

Before (v0.1.0)

After (v0.4.1)

zod

31 symbols

577

axios

0

83

uuid

0

23

chalk

19

32

fastify

51

~100+

express

0

13 (via @types/express)

How It Works

┌──────────────────┐       ┌──────────────────────────────────────────────┐
│  AI Coding Agent │ ◄──── │          ts-docs-mcp                         │
│  (Cursor, Claude │ MCP   │   (MCP Server via stdio)                     │
│   Code, etc.)    │       │                                              │
└──────────────────┘       │  get_package_docs("zod")                     │
         │                  │    ↓                                        │
         │   "Here is the  │  1. npm registry → package metadata          │
         │   full API      │  2. GitHub raw → JSDoc from .ts source       │
         │   documentation"│  3. BFS re-export resolution (parallel)      │
         ▼                  │  4. npm tarball → .d.ts parsing (no JSDoc?) │
  Writes correct code       │  5. @types/{name} fallback (JS-only)        │
                            │  6. Merge + dedup → Markdown                │
                            │  7. XDG cache (24h TTL)                     │
                            └──────────────────────────────────────────────┘

Tools

Tool

Description

get_package_docs

Get API docs for any npm package. Optional query, version, subpath.

Examples

# Latest version
get_package_docs("zod")

# Specific version
get_package_docs("zod", version="3.23.8")

# Subpath export (e.g. zod/v4/classic)
get_package_docs("zod", subpath="v4/classic")

# Query a specific symbol
get_package_docs("zod", query="transform")

Fallback chain

GitHub .ts (JSDoc + declarations)
  → BFS re-export resolution (depth=2, concurrency=5)
    → merge: GitHub .d.ts (from tarball, with re-export following)
      → if 0 symbols: DefinitelyTyped (@types/{name})
        → merge all results, dedup by name (GitHub takes priority)

What the model gets

## findByEmail (function)
> Find a user by their email address.
> @param email — The email to search for
> @returns The user object or null

```typescript
export function findByEmail(email: string, includeDeleted?: boolean): User | null;

Parameters:

  • email — The email to search for

  • includeDeleted — Whether to include deleted users

Returns: The user object or null


Full signatures, no truncation. `@param`, `@returns`, `@deprecated`, `@example` are preserved.

### Cache

Documentation is cached in `~/.cache/ts-docs-mcp/` (XDG-compatible), keyed by `package@version`. TTL is 24 hours. Old entries are cleaned up after 7 days.

---

## Usage

### Quick start

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "ts-docs-mcp": {
      "command": "npx",
      "args": ["-y", "ts-docs-mcp"]
    }
  }
}

Cursor: Settings → MCP → Add Server → paste the config above. Claude Code: claude mcp add ts-docs-mcp -- npx -y ts-docs-mcp VS Code / Copilot: .vscode/mcp.json → add the entry.

Requirements

  • Node.js 20+

  • Internet access (fetches from npm registry, GitHub, npm tarballs)

  • Package must be on npm with a public GitHub repository (or have @types/ types)

Examples

Get the full API overview:

You → "Show me the axios API"
Agent → calls get_package_docs("axios")
     → gets 83 symbols: types, interfaces, classes, functions

Find a specific symbol:

You → "How do I use Zod's transform method?"
Agent → calls get_package_docs("zod", query="transform")
     → gets ZodEffects.transform with full signature + JSDoc

Why not just use the README / training data?

Source

Coverage

Version-aware

Freshness

Training data

Variable

❌

6-24 months stale

README

~20% of API

❌

Often stale

ts-docs-mcp

All exports

✅ Exact version

✅ Real-time

TypeScript .d.ts files + GitHub source are the canonical source of truth — they always reflect the exact installed version.

Development

git clone https://git.827482.xyz/xvantz/ts-docs-mcp.git
cd ts-docs-mcp
npm install
npm run build
npm test          # 43 unit tests (5 test files)
npm run test:integration  # network tests (skipped in CI)

Project structure

src/
├── registry.ts   — npm package metadata + HTTP helpers
├── github.ts     — GitHub raw source fetching (BFS, parallel)
├── tarball.ts    — .d.ts extraction from tarball + DefinitelyTyped
├── parser.ts     — Two-phase JSDoc + declaration parser
├── format.ts     — Markdown output (summary + detail)
├── throttle.ts   — Per-endpoint token-bucket rate limiter
├── cache.ts      — XDG file cache with 24h TTL
├── types.ts      — PublicSymbol, PackageInfo interfaces
└── index.ts      — MCP server (thin handler)

License

MIT

Built because AI coding agents deserve better than hallucinated APIs.

Available Tools

1 tool
get_package_docsA

Get accurate, version-specific API documentation for any npm package.

WHEN TO USE THIS TOOL:

  • ALWAYS call this tool when the user asks about a library, package, or framework.

  • ALWAYS call this tool BEFORE writing code that uses an external npm dependency.

  • ALWAYS call this tool when you need to know function signatures, types, interfaces, classes, or exports from a package.

  • Call this tool when the user says things like: 'use zod', 'write with axios', 'how does fastify work', 'express route handler', 'prisma schema', 'lodash merge'.

  • Call this tool when a package version is mentioned: 'zod@3.23', 'express 4.18' — pass it as the 'version' parameter.

DO NOT rely on training data for package APIs — training data is months out of date. This tool fetches the EXACT version the user needs from the actual source code.

Supports:

  • Specific version: get_package_docs('zod', version='3.23.8')

  • Subpath exports: get_package_docs('zod', subpath='v4/classic')

  • Symbol search: get_package_docs('zod', query='transform')

Documentation is cached for 24 hours — repeated calls for the same package+version are instant.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryNoOptional — find a specific symbol within the package.
packageYesnpm package name, e.g. 'zod', 'express', '@prisma/client'
subpathNoOptional — subpath export entry, e.g. 'v4/classic' for zod/v4/classic.
versionNoOptional — exact version to fetch (e.g. '3.23.8'). Defaults to latest.

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral disclosure burden. It discloses that docs are cached for 24 hours, that the tool fetches from actual source code, and implies it's a read-only fetch operation with no side effects. It could mention rate limits or network failure behavior, but the 24-hour caching and source-fetch behavior are meaningful transparency disclosures. The guidance not to trust training data further clarifies expected behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well structured with clear sections (WHEN TO USE, DO NOT, Supports). It's longer than minimal but every line earns its place — the trigger phrases and usage examples are genuinely informative. The only minor critique is some redundancy between 'ALWAYS call this tool when the user asks about a library/package/framework' and subsequent bullet points, but overall it's efficient and front-loaded with the most important directive.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a 4-parameter tool with no output schema, so the description carries responsibility for explaining both inputs and expected returns. It does an excellent job on inputs (usage patterns, trigger phrases, version handling) and mentions fetching from source code and caching, which implies the return is structured API documentation. It could explicitly state what the return value contains (e.g., signatures, examples) but the level of detail is strong for a documentation-fetch tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all 4 parameters are already documented in the input schema. The description adds value by showing concrete usage patterns (get_package_docs('zod', version='3.23.8'), subpath='v4/classic', query='transform') that go beyond the schema's bare definitions. This meets the baseline 3 for compensating beyond high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear, specific statement: 'Get accurate, version-specific API documentation for any npm package.' It names the verb (get), resource (API documentation), and scope (version-specific, npm). The WHEN TO USE section reinforces purpose with concrete trigger examples ('use zod', 'express route handler'). No ambiguity about what this tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

This is exemplary. The description gives explicit when-to-use rules ('ALWAYS call this tool when the user asks about a library'), specific trigger phrases, and a direct warning to NOT rely on training data for package APIs — effectively indicating when this tool is authoritative over other sources. It also demonstrates usage patterns for version, subpath, and query parameters.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev0.6.3
    • First observedget_package_docs
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0
Disambiguation5/5

With only a single tool, there is no ambiguity whatsoever — get_package_docs has a clearly defined purpose of fetching version-specific npm package documentation. There are no overlapping tools to confuse.

Naming Consistency4/5

The single tool name 'get_package_docs' follows the conventional verb_noun pattern and is descriptive. However, with only one tool, there's no pattern to evaluate for consistency across a set.

Tool Count2/5

A single tool for package documentation is borderline thin. While it's a focused purpose, a fuller server might include tools for discovering packages, listing versions, or comparing docs — but the single tool does serve a coherent narrow scope.

Completeness3/5

The tool covers fetching docs with version, subpath, and symbol query options, which handles the core use case of retrieving accurate package API info. However, there are no companion tools for related operations like listing supported packages, listing available versions, or fetching type definitions separately, creating minor gaps.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/xvantz/ts-docs-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server