Content
# cap-shim — capability shim for AI models
> Supplement backend capabilities for AI models: Image recognition (Qwen-VL) + Internet search (Tavily).
both **stdio** and **HTTP/SSE** transport layers. Compatible with any MCP-enabled agent.
## Quick Start
```bash
git clone https://github.com/x12315/cap-shim-mcp.git
cd cap-shim-mcp
./setup.sh
```
## Two Operation Modes
### Local stdio (Mac / Single Machine)
```bash
uv run cap-shim stdio vision
uv run cap-shim stdio search
```
Agent configuration reference `.mcp.json`.
###/SSE (Home Server Sharing)
```bash
uv run cap-shim serve vision --port 8080
uv run cap-shim serve search --port 8081
```
Deployment to systemd reference `/`.
Remote client configuration:
{
"mcp":wen-vision": { "transport": "sse", " "http://100.115.123.9:8080/sse "tavily-search": { "transport": "sse", "url": "http://100.115.123.9:8081/sse" }
}
}
```
## API Keys
All concentrated in `~cp-servers/.env` or project root `.env`:
```bash
DASHSCOPE_API_KEY=sk-xxx # Alibaba Cloud DashScope → https://dashscope.console.aliyun.com
TAVILY_API_KEY=tvly-xxx # Tavily Search://avily.comAlso, can specify custom path through environment variable `CAP_SHIM_ENV_FILE`.
## Image Input Support
The ` parameter of `analyze_image` formats:
| Format | Example | Applicable Scenario |
|------|------|--------- Local Path | `/Users/.../screenshot.png` | stdio mode |
| | `https://example.jpg` | General |
| base64 data URI | `data:image64,/9j/...`/SSE remote mode |
Server-side automatically uses Pillow to scale large images to MAX_DIM (2048px) and compress JPEG.
## Directory Structure
-shim-mcp/
├──ap_shim/ # Python package
│ ├── config.py # Unified configuration
│ ├── server.py # MCP protocol processing
│ ├── vision.py # Image recognition ├── search.py # Internet search
│ ├── transports # stdio + HTTP/SSE transport layer
│ └── # CLI entry
/systemd/ # systemd unit template
├── setup.sh # One-click local deployment
└── .mcp.json # Agent registration reference
```
## Deployment to Home Server
```bash
# On alpha (Arch Linux)
git clone https://github12315/cap-shim-mcp.git ~/cap-shim-mcp
cd ~/cap-shim-mcp
uv sync
cp .env.example .env # Edit and fill in real key
# Install systemd user unit
mkdir -p ~/.config/systemd/user
cp deploy/systemd/*.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now m mcp-search
```
## Design Principles
- **Transport Layer Separation**: Core logic is not bound to stdio or HTTP, running in two modes with the same code
- **Cross-Platform**: Pillow replaces macOS sips, compatible with Linux/Mac
- **API Key Centralization**: Managed in one place, injected through environment variables
- **Zero Mandatory Out-of-the-box experience parameters have reasonable default values
