# Zip MCP Server

An MCP (Model Context Protocol) server for integrating with the Zip API, built with [FastMCP](https://github.com/jlowin/fastmcp).

## Installation

```bash
pip install ziphq-mcp
```

Or with uv:

```bash
uv pip install ziphq-mcp
```

## Usage

### With Claude Code / Claude Desktop

Add to your MCP configuration (e.g., `~/.claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "zip": {
      "command": "uv",
      "args": ["run", "--with", "ziphq-mcp", "ziphq-mcp"],
      "env": {
        "ZIP_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Running directly

```bash
# Set the API key via environment variable
export ZIP_API_KEY="your-api-key-here"

# Run with uv (recommended)
uv run --with ziphq-mcp ziphq-mcp

# Or if installed globally
ziphq-mcp
```

## Available Tools

| Tool | Description |
|------|-------------|
| `zip_search_requests` | Search for purchase requests with filters (status, priority, requester, vendor, department, dates, etc.) |
| `zip_get_request` | Get details of a specific purchase request by ID |

### zip_search_requests Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `request_number` | string | The request number in Zip |
| `status` | int | 1=AWAITING_APPROVAL, 2=REJECTED, 3=APPROVED, 4=CANCELED, 5=CLOSED, 6=PAUSED |
| `priority` | int | 0=Urgent, 1=Normal |
| `requester_id` | string | User ID (UUID) of the requester |
| `requester_name` | string | Requester name |
| `request_type` | string | PURCHASE_REQUEST, SECURITY_REVIEW, VENDOR_ONBOARDING, SOURCING_REQUEST, PO_CHANGE_ORDER |
| `department_name` | string | Name of the department |
| `department_id` | list[string] | List of department IDs (UUIDs) |
| `vendor_name` | string | Name of the vendor |
| `vendor_id` | string | ID (UUID) of the vendor |
| `created_after` | int | Epoch timestamp (seconds) |
| `created_before` | int | Epoch timestamp (seconds) |
| `completed_after` | int | Epoch timestamp (seconds) |
| `completed_before` | int | Epoch timestamp (seconds) |
| `last_updated_after` | int | Epoch timestamp (seconds) |
| `last_updated_before` | int | Epoch timestamp (seconds) |
| `include_attributes` | bool | Include custom fields in response |
| `sort_by` | string | create_time, complete_time, last_updated_time, request_number, status |
| `sort_order` | string | asc, desc |
| `page_size` | int | Number of results per page |
| `page_token` | string | Pagination token for next page |

## Configuration

The server requires a Zip API key. You can provide it in two ways:

1. **Environment variable**: Set `ZIP_API_KEY`
2. **MCP configuration**: Pass it via the `env` section in your MCP config

## Project Structure

```
zip_mcp/
├── src/
│   ├── __init__.py
│   ├── app.py          # FastMCP instance and configuration
│   ├── server.py       # Main entry point
│   └── tools/
│       ├── __init__.py
│       └── requests.py # Purchase request tools
├── pyproject.toml
└── README.md
```

## Development

```bash
# Navigate to the zip_mcp directory
cd zip_mcp

# Install dev dependencies
uv sync --dev

# Run tests
uv run pytest

# Format code
uv run ruff format .
uv run ruff check --fix .
```

## Publishing to PyPI

```bash
# Build the package
uv build

# Upload to PyPI (requires PyPI credentials)
uv publish
```

## License

MIT
