bun-doc-mcp: Instructions file for Claude Code

Bun Documentation MCP Server

This is a Model Context Protocol (MCP) server that provides access to Bun documentation through a file system-like interface.

Project Overview

This MCP server downloads Bun documentation from GitHub and provides access through a file system-like interface. It automatically caches documentation locally and allows AI assistants to browse and read Bun documentation progressively, reducing unnecessary information transfer.

Technical Decisions

Project Structure

• Single index.ts implementation
• Minimal dependencies: @modelcontextprotocol/sdk and zod

Documentation Slugs

• Documentation entries are addressed by slug (e.g., runtime/bun-apis, guides/http)
• Slugs mirror the Bun docs navigation structure; no custom URI scheme required
• Markdown files resolve by slug without the .md suffix

Documentation Source

• Downloads from GitHub using git sparse checkout for efficiency
• Automatically caches in $HOME/.cache/bun-doc-mcp/{version}/docs
• Uses docs/nav.ts to determine available pages and structure

MCP Tools

• grep_bun_docs: regex search over cached documentation with optional path filters and flags
• read_bun_doc: return raw markdown for a documentation slug

Development Guidelines

Code Style

• Keep responses concise - this is a CLI tool
• No unnecessary comments in code
• Follow existing patterns in the codebase

Testing Guidelines

MCP Server Testing

After making code changes that affect MCP functionality:

1. User must restart MCP server - ask user to restart
2. Wait for restart confirmation - Don't proceed until user confirms restart
3. Test core functionality using MCP tools:
   • Test grep_bun_docs
   • Test read_bun_doc
   • Add extra checks that make sense for your change; don't stop at the canned examples

Command-line Testing

Since the bash tool doesn't have TTY, use JSON-RPC protocol for testing:

# Test search functionality
echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"grep_bun_docs","arguments":{"pattern":"WebSocket"}},"id":1}' | bun run index.ts 2>/dev/null | jq '.result.content[0].text | fromjson | length'

# Test reading a document by slug
echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"read_bun_doc","arguments":{"path":"runtime/bun-apis"}},"id":1}' | bun run index.ts 2>/dev/null | jq -r '.result.content[0].text' | head -20

# Check initialization output (use timeout to avoid hanging)
timeout 1s bun run index.ts 2>&1 | grep -E "\\[Indexing\\]|\\[Warning\\]"

# Add any extra checks relevant to your change (different slugs, regex flags, etc.)