MiniMax Coding Plan extension for pi coding agent - provides web_search and understand_image tools
npm install @imsus/pi-extension-minimax-coding-plan-mcp!npm version
!npm downloads
!License
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.
- š 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
- pi coding agent installed
- MiniMax Coding Plan subscription
- Node.js >= 18.0.0
- 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
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
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
Use the pi install command to install packages from npm, git, or HTTPS URLs.
``bash`
pi install npm:@imsus/pi-extension-minimax-coding-plan-mcp
`bash`
pi install git:https://github.com/imsus/pi-extension-minimax-coding-plan-mcp
Or with a version tag:
`bash`
pi install git:https://github.com/imsus/pi-extension-minimax-coding-plan-mcp@v1.0.0
`bash`
pi install https://github.com/imsus/pi-extension-minimax-coding-plan-mcp
Add -l flag to install to project settings (.pi/settings.json):
`bash`
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.
Use --extension or -e to try the package without installing:
`bash`
pi -e npm:@imsus/pi-extension-minimax-coding-plan-mcp
pi -e git:https://github.com/imsus/pi-extension-minimax-coding-plan-mcp
`bash`
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
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
The extension checks for the API key in this order:
1. Environment variable (recommended for per-session config)
`bash`
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`
json`
{
"minimax": {
"type": "api_key",
"key": "your-api-key-here"
}
}
> Note: Use /minimax-configure command to set up your API key interactively.
Set or update your API key:
`bash`
pi
/minimax-configure --key your-api-key-here
This saves to ~/.pi/agent/auth.json for permanent storage.
`bashShow help
/minimax-configure --help
$3
`bash
/minimax-status
`Shows current configuration status and available tools.
Usage
$3
Search for current information:
`
Search the web for TypeScript best practices 2026web_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
$3
Analyze images with AI:
`
Understand this screenshotunderstand_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
`typescript
// 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
$3
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------- |
| query | string | ā | Search query (2-500 characters) |
Example:
`typescript
web_search({
query: "Pi coding agent extensions guide"
})
`Returns: List of search results with titles, URLs, snippets, and follow-up suggestions.
$3
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------ |
| prompt | string | ā | Question or analysis request (1-1000 characters) |
| image_url | string | ā | Image URL or local file path |
Example:
`typescript
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 promptsSkills 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
`bash
Install dependencies
npm installStart pi - it loads TypeScript directly
pi
`No build step needed! pi loads
.ts files directly from the extensions/ directory.
`$3
`bash
Login to npm
npm loginPublish
npm publishPublish with tag
npm publish --tag beta
`Troubleshooting
$3
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)
$3
1. Check pi logs for errors
2. Verify package is in
~/.pi/settings.json
3. Ensure npm install completed successfully
4. Try restarting pi$3
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$3
Use absolute paths or paths relative to current directory:
`typescript
understand_image({
prompt: "Analyze this file",
image_url: "/Users/username/screenshots/error.png"
// or
image_url: "./screenshots/error.png"
})
`$3
Make sure the
~/.pi/agent/auth.json file has the correct format:
`json
{
"minimax": {
"type": "api_key",
"key": "your-api-key-here"
}
}
`Use
/minimax-configure --show to check if your key is configured correctly.$3
If changes don't appear after updating, clear the cached version:
`bash
Remove the cached git repository
rm -rf ~/.pi/agent/git/github.com/imsus/pi-extension-minimax-coding-plan-mcpRestart 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'`)MIT License - see LICENSE file for details.
- š Documentation
- š Issues
- š¬ Discussions
---
npm Package: @imsus/pi-extension-minimax-coding-plan-mcp
- ⨠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