@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.

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

$3

- 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.

$3

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

$3

`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
`

$3

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

$3

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.

$3

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
`

$3

`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
`

Configuration

$3

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

$3

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.

$3

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.

$3

`bash


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
`

$3

`bash
/minimax-status
`

Shows current configuration status and available tools.

Usage

$3

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

$3

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

`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 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

`bash


Install dependencies

npm install

Start 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 login

Publish

npm publish

Publish 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-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

$3

- ✨ 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