pubdev_mcp_bridge #

AI assistants hallucinate Dart APIs. This fixes it.

pubdev_mcp_bridge serve dio

Extracts accurate API documentation from any pub.flutter-io.cn package and serves it via MCP, giving AI assistants like Claude, Cursor, and Windsurf perfect knowledge of Dart libraries.

Why This Matters #

• Any package: Works with all public packages on pub.flutter-io.cn
• Any MCP client: Compatible with Claude Code, Claude Desktop, Cursor, Windsurf, Cline, and other MCP-enabled tools
• Zero configuration: One command to extract and serve documentation
• Always accurate: Extracts documentation directly from source code using the Dart analyzer
• Experimental features: Supports packages using macros, records, dot-shorthands, and other modern Dart syntax

Installation #

Prerequisites: Dart SDK 3.7.0 or later

Install globally from pub.flutter-io.cn:

dart pub global activate pubdev_mcp_bridge

Make sure the pub cache bin directory is in your PATH:

• macOS/Linux: Add export PATH="$PATH":"$HOME/.pub-cache/bin" to your shell profile
• Windows: Add %LOCALAPPDATA%\Pub\Cache\bin to your PATH

Or install from source:

git clone https://github.com/heyaphra/pubdev_mcp_bridge.git
cd pubdev_mcp_bridge
dart pub get
dart pub global activate --source path .

Usage #

serve <package> - Start MCP Server #

Extracts documentation (if not cached) and starts an MCP server:

# Serve the latest version
pubdev_mcp_bridge serve riverpod

# Serve a specific version
pubdev_mcp_bridge serve riverpod --version 2.5.0

# Force re-extraction (ignore cache)
pubdev_mcp_bridge serve riverpod --refresh

extract <package> - Extract Documentation Only #

Downloads and extracts documentation without starting a server:

pubdev_mcp_bridge extract freezed
pubdev_mcp_bridge extract freezed --version 2.4.0

list - List Cached Packages #

Shows all packages with cached documentation:

pubdev_mcp_bridge list
# Output:
# Cached packages:
#   riverpod@2.6.1
#   dio@5.4.0
#   music_notes@0.24.0

clean - Remove Cached Data #

# Remove a specific package (all versions)
pubdev_mcp_bridge clean riverpod

# Remove a specific version
pubdev_mcp_bridge clean riverpod --version 2.5.0

# Remove all cached data
pubdev_mcp_bridge clean --all

Connecting to AI Assistants #

Claude Code #

Use the claude mcp add command:

# Add a server (if installed globally)
claude mcp add riverpod pubdev_mcp_bridge serve riverpod

# Or run directly from the project directory
claude mcp add riverpod dart run /path/to/pubdev_mcp_bridge/bin/pubdev_mcp_bridge.dart serve riverpod

Scope options:

# Add to current project only
claude mcp add --scope project riverpod pubdev_mcp_bridge serve riverpod

# Add globally (available in all projects)
claude mcp add --scope user riverpod pubdev_mcp_bridge serve riverpod

Verify registration:

claude mcp list

Claude Desktop #

Add the server to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "riverpod": {
      "command": "pubdev_mcp_bridge",
      "args": ["serve", "riverpod"]
    }
  }
}

Or if not installed globally:

{
  "mcpServers": {
    "riverpod": {
      "command": "dart",
      "args": ["run", "/path/to/pubdev_mcp_bridge/bin/pubdev_mcp_bridge.dart", "serve", "riverpod"]
    }
  }
}

Cursor / Windsurf #

Add to your MCP settings file (location varies by editor):

{
  "mcpServers": {
    "dio": {
      "command": "pubdev_mcp_bridge",
      "args": ["serve", "dio"]
    }
  }
}

Other MCP Clients #

Any tool that supports the Model Context Protocol can connect to pubdev_mcp_bridge. Consult your tool's documentation for MCP server configuration.

Available Tools #

Example: Accurate API Responses #

With the music_notes package server running, AI assistants can answer questions with perfect accuracy:

User: "How do I create a chord in the music_notes package?"

AI Assistant (with pubdev_mcp_bridge):

You can create a Chord using its constructor:

  Chord(this._items)

The Chord class is generic (Chord<T>) and implements Transposable<Chord<T>>.

Example usage:
  final chord = Chord([Note.c, Note.e, Note.g]);
  
You can also get the chord's pattern:
  ChordPattern pattern = chord.pattern();

Or transpose it:
  Chord<T> transposed = chord.transposeBy(Interval.perfectFourth);

Without pubdev_mcp_bridge: Hallucinated APIs, outdated examples, incorrect method signatures.

How It Works #

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   pub.flutter-io.cn   │────▶│  Extractor  │────▶│    Cache    │
│   (HTTP)    │     │  Pipeline   │     │   (JSON)    │
└─────────────┘     └─────────────┘     └─────────────┘
                                               │
                                               ▼
                    ┌─────────────┐     ┌─────────────┐
                    │     AI      │◀────│ MCP Server  │
                    │  Assistant  │     │  (stdio)    │
                    └─────────────┘     └─────────────┘

pubdev_mcp_bridge downloads packages from pub.flutter-io.cn, extracts API documentation using the Dart analyzer, caches it locally as JSON, and serves it via an MCP server. AI assistants query the server to get accurate, up-to-date information about Dart packages.

Limitations #

• Path dependencies: Packages with path dependencies (e.g., path: ../sibling_package in monorepos) will fail during dart pub get because the sibling packages don't exist in the extracted directory. Try a different version or contact the package maintainer.
• Private packages: Only public packages on pub.flutter-io.cn are supported. The tool uses unauthenticated HTTP requests to the pub.flutter-io.cn API.
• SDK constraints: Packages requiring a newer Dart SDK than you have installed will fail during dart pub get. For example, if a package requires sdk: ^3.8.0 but you have Dart 3.7.0, extraction will fail. Upgrade your Dart SDK or try an older package version.

Troubleshooting #

Server starts but tools don't appear

Restart your AI assistant or IDE. Some clients cache MCP server capabilities.

Extraction fails for a specific package

Try a different version:

pubdev_mcp_bridge serve package_name --version 1.2.3

Cache issues

Clear the cache and re-extract:

pubdev_mcp_bridge clean --all
pubdev_mcp_bridge serve package_name --refresh

Check cached documentation

# List cached packages
ls ~/.pubdev_mcp_cache/docs/

# View cached JSON
cat ~/.pubdev_mcp_cache/docs/dio-5.4.0.json | head -100

Windows users: Replace ~/.pubdev_mcp_cache with %LOCALAPPDATA%\pubdev_mcp_cache

Contributing #

Contributions are welcome! See CONTRIBUTING.md for development setup, architecture details, and guidelines.

License #

MIT License - see LICENSE file for details.

Acknowledgments #

• Built with dart_mcp from the Dart team
• Extraction powered by analyzer from the Dart team
• Model Context Protocol by Anthropic