@imsus/pi-extension-minimax-coding-plan-mcp

MiniMax MCP (Model Context Protocol) extension for pi coding agent that provides AI-powered web search and image understanding capabilities.

Since pi doesn't natively support MCP, this extension bridges that gap by implementing the MiniMax MCP API directly as pi tools.

Features

• 🔍 Web Search - Search the web for current information with intelligent results and suggestions
• 🖼️ Image Understanding - Analyze images with AI for descriptions, OCR, code extraction, and visual analysis
• 📖 Built-in Skills - Guides the LLM on when and how to use each tool effectively
• ⚡ Easy Configuration - Configure via environment variables or pi settings files
• 🔄 Hot Reload - Changes apply without restarting pi
• 🎨 Rich UI - Custom rendering with progress indicators and status updates

Prerequisites

• pi coding agent installed
• MiniMax Coding Plan subscription
• Node.js >= 18.0.0

Related Resources

• PyPI Package: minimax-coding-plan-mcp - The official Python MCP server this implementation is based on
• MiniMax Platform: api.minimax.io - Global API endpoint
• MiniMax Platform (China): api.minimaxi.com - Mainland China API endpoint

Why This Extension?

The MiniMax Coding Plan provides powerful MCP tools for web search and image understanding. However, pi doesn't natively support MCP protocol.

This extension implements those same capabilities as native pi tools, so you get:

• The same MiniMax MCP functionality you love
• Full integration with pi's tool system
• Custom rendering and progress indicators
• Built-in skills to help the LLM use tools effectively

About This Implementation

This extension was reverse-engineered from the official MiniMax Coding Plan MCP Python package. The original package provides MCP protocol tools that work with MCP-compatible clients like Claude Desktop, Cursor, and Windsurf.

By analyzing the Python implementation, this extension recreates the same functionality directly as pi native tools, providing:

• Identical API endpoints and behavior
• Matching request/response formats
• Consistent error handling
• Seamless pi integration

Installation

Use the pi install command to install packages from npm, git, or HTTPS URLs.

Install from npm

pi install npm:@imsus/pi-extension-minimax-coding-plan-mcp

Install from git

pi install git:https://github.com/imsus/pi-extension-minimax-coding-plan-mcp

Or with a version tag:

pi install git:https://github.com/imsus/[email protected]

Install from HTTPS URL

pi install https://github.com/imsus/pi-extension-minimax-coding-plan-mcp

Project Installation

Add -l flag to install to project settings (.pi/settings.json):

pi install -l npm:@imsus/pi-extension-minimax-coding-plan-mcp

Project settings can be shared with your team, and pi will auto-install missing packages on startup.

Try Without Installing

Use --extension or -e to try the package without installing:

pi -e npm:@imsus/pi-extension-minimax-coding-plan-mcp
pi -e git:https://github.com/imsus/pi-extension-minimax-coding-plan-mcp

Manage Packages

pi list              # show installed packages
pi update            # update all non-pinned packages
pi remove npm:@imsus/pi-extension-minimax-coding-plan-mcp  # remove a package

Configuration

Get Your API Key

1. If you haven't subscribed yet, visit MiniMax Coding Plan to subscribe
2. Once subscribed, go to API Key page to get your API key

Configuration Priority

The extension checks for the API key in this order:

1. Environment variable (recommended for per-session config)

   export MINIMAX_API_KEY="your-api-key-here"
   export MINIMAX_API_HOST="https://api.minimax.io"  # optional, default

2. Auth file (~/.pi/agent/auth.json) - persistent across sessions

   {
     "minimax": {
       "type": "api_key",
       "key": "your-api-key-here"
     }
   }

Note: Use /minimax-configure command to set up your API key interactively.

In-Session Configuration

Set or update your API key:

pi
/minimax-configure --key your-api-key-here

This saves to ~/.pi/agent/auth.json for permanent storage.

Configuration Commands

# Show help
/minimax-configure --help

# Show current status
/minimax-configure --show

# Set API key directly
/minimax-configure --key your-api-key-here

# Clear configuration
/minimax-configure --clear

Check Status

/minimax-status

Shows current configuration status and available tools.

Usage

Web Search

Search for current information:

Search the web for TypeScript best practices 2026

web_search({
  query: "latest React 19 features announcement"
})

Returns search results with titles, URLs, snippets, and suggestions.

When to use:

• Current events and news
• Latest releases and updates
• Fact verification with recent information
• Technical documentation that may have changed

Image Understanding

Analyze images with AI:

Understand this screenshot

understand_image({
  prompt: "What error is shown in this screenshot?",
  image_url: "https://example.com/error.png"
})

Image Formats

• Supported: JPEG, PNG, GIF, WebP
• Maximum size: 20MB
• Sources: HTTP/HTTPS URLs or local file paths

Example Use Cases

// Describe image content
understand_image({
  prompt: "Describe what's in this image in detail",
  image_url: "https://example.com/photo.jpg"
})

// Extract text (OCR)
understand_image({
  prompt: "Extract all text from this image",
  image_url: "./screenshots/document.png"
})

// Analyze UI/UX
understand_image({
  prompt: "Analyze this UI design and suggest improvements",
  image_url: "https://example.com/mockup.png"
})

// Code from screenshot
understand_image({
  prompt: "What code is shown in this screenshot? Transcribe it exactly.",
  image_url: "./error-screenshot.jpg"
})

// Debug errors
understand_image({
  prompt: "What is the error message and stack trace in this screenshot?",
  image_url: "./bug-screenshot.png"
})

When to use:

• Screenshots of errors or UI issues
• Diagrams, charts, or visual content
• Extracting text from images (OCR)
• Analyzing code in screenshots
• Visual debugging

Tools Reference

web_search

| Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------- | | query | string | ✓ | Search query (2-500 characters) |

Example:

web_search({
  query: "Pi coding agent extensions guide"
})

Returns: List of search results with titles, URLs, snippets, and follow-up suggestions.

understand_image

| Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------------------ | | prompt | string | ✓ | Question or analysis request (1-1000 characters) | | image_url | string | ✓ | Image URL or local file path |

Example:

understand_image({
  prompt: "What is in this image?",
  image_url: "https://example.com/screenshot.png"
})

Returns: AI analysis of the image content based on your prompt.

Extension Commands

| Command | Description | | -------------------- | ------------------------------- | | /minimax-configure | Configure API key | | /minimax-status | Show configuration status | | /reload | Hot reload extension (built-in) |

Skills

This extension includes built-in skills to help the LLM understand when and how to use each tool:

• /skill:minimax-web-search - Guidance on effective web search queries
• /skill:minimax-image-understanding - Tips for image analysis prompts

Skills are automatically included in the system prompt when relevant.

Learn More

• MiniMax MCP Documentation - Official MCP API guide
• MiniMax Coding Plan - Subscribe to access MCP tools
• minimax-coding-plan-mcp (PyPI) - Official Python MCP server
• pi coding agent - The coding agent this extension supports

Project Structure

pi-extension-minimax-coding-plan-mcp/
├── extensions/               # TypeScript extension (loaded directly by pi)
│   └── index.ts              # Source code
├── skills/                   # Skills directory (auto-discovered by pi)
│   ├── minimax-web-search/
│   │   └── SKILL.md          # Web search skill
│   └── minimax-image-understanding/
│       └── SKILL.md          # Image understanding skill
├── package.json              # npm package config
├── REVERSE_ENGINEERING.md    # Reverse engineering documentation
└── README.md                 # This file

Development

# Install dependencies
npm install

# Start pi - it loads TypeScript directly
pi

No build step needed! pi loads .ts files directly from the extensions/ directory.

### Publishing

```bash
# Login to npm
npm login

# Publish
npm publish

# Publish with tag
npm publish --tag beta

Troubleshooting

API Key Not Working

1. Get your API key at https://platform.minimax.io/user-center/payment/coding-plan
2. Check key hasn't expired
3. Ensure you have the Coding Plan subscription (not just MiniMax account)

Extension Not Loading

1. Check pi logs for errors
2. Verify package is in ~/.pi/settings.json
3. Ensure npm install completed successfully
4. Try restarting pi

Tool Returns Error

1. Check /minimax-status for configuration
2. Verify network connectivity
3. Check API key has required permissions
4. For detailed error information, check the Trace-Id in error messages
5. Compare behavior with minimax-coding-plan-mcp if issues persist

Local File Paths Not Working

Use absolute paths or paths relative to current directory:

understand_image({
  prompt: "Analyze this file",
  image_url: "/Users/username/screenshots/error.png"
  // or
  image_url: "./screenshots/error.png"
})

API Key Not Saved to auth.json

Make sure the ~/.pi/agent/auth.json file has the correct format:

{
  "minimax": {
    "type": "api_key",
    "key": "your-api-key-here"
  }
}

Use /minimax-configure --show to check if your key is configured correctly.

Extension Not Updating

If changes don't appear after updating, clear the cached version:

# Remove the cached git repository
rm -rf ~/.pi/agent/git/github.com/imsus/pi-extension-minimax-coding-plan-mcp

# Restart pi to re-clone the latest version

Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature')
5. Open Pull Request

License

MIT License - see LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions

npm Package: @imsus/pi-extension-minimax-coding-plan-mcp

Changelog

v1.0.0 (2026-01-29)

• ✨ Initial release
• 🔍 web_search tool with rich results
• 🖼️ understand_image tool with AI analysis
• 📖 Built-in skills for tool guidance
• ⚙️ Configuration commands (/minimax-configure, /minimax-status)
• 🎨 Rich UI with custom rendering
• 🔄 Hot reload support