Metadata-Version: 2.4
Name: yirifi-ops-mcp-hub
Version: 0.4.4
Summary: MCP servers for Yirifi Ops - expose REST APIs as MCP tools for AI assistants
Author-email: Yirifi <dev@yirifi.ai>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/yirifi/yirifi-ops-mcp-hub
Project-URL: Repository, https://github.com/yirifi/yirifi-ops-mcp-hub
Project-URL: Issues, https://github.com/yirifi/yirifi-ops-mcp-hub/issues
Keywords: mcp,model-context-protocol,fastmcp,ai,llm,claude
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: click>=8.0
Requires-Dist: structlog>=24.0
Requires-Dist: uvicorn[standard]>=0.30
Requires-Dist: starlette>=0.38
Requires-Dist: aiolimiter>=1.1.0
Requires-Dist: tenacity>=8.2.0
Requires-Dist: toon-format>=0.1.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"

# yirifi-ops-mcp-hub

MCP (Model Context Protocol) servers for Yirifi Ops - expose REST APIs as MCP tools for AI assistants like Claude.

## Installation

```bash
# Using uvx (recommended - no install needed)
uvx yirifi-ops-mcp-hub --version

# Using pip
pip install yirifi-ops-mcp-hub

# Using uv
uv pip install yirifi-ops-mcp-hub
```

### Optional: TOON Format (Compact Responses)

For optimized token-efficient responses, install toon-format (currently in beta):

```bash
# Install from GitHub (recommended for beta)
pip install git+https://github.com/toon-format/toon-python.git

# Or clone and install locally
git clone https://github.com/toon-format/toon-python.git
cd toon-python
uv sync
```

### Troubleshooting uvx Cache Issues

If `uvx` doesn't pick up the latest version after an upgrade:

```bash
# Clear cached environments and refresh
rm -rf ~/.cache/uv/environments* && uvx --refresh yirifi-ops-mcp-hub --version
```

## Quick Start

### Claude Code Configuration

Add to your Claude Code MCP settings (`~/.claude.json` or project `.mcp.json`):

```json
{
  "mcpServers": {
    "yirifi-ops": {
      "command": "uvx",
      "args": ["yirifi-ops-mcp-hub"],
      "env": {
        "YIRIFI_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

Or with specific options:

```json
{
  "mcpServers": {
    "yirifi-dev": {
      "command": "uvx",
      "args": ["yirifi-ops-mcp-hub", "--mode=dev"],
      "env": {
        "YIRIFI_API_KEY": "your_api_key_here"
      }
    },
    "yirifi-prd": {
      "command": "uvx",
      "args": ["yirifi-ops-mcp-hub", "--mode=prd"],
      "env": {
        "YIRIFI_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### CLI Options

```bash
# Run with all services (default)
YIRIFI_API_KEY=your_key uvx yirifi-ops-mcp-hub

# Run specific service
YIRIFI_API_KEY=your_key uvx yirifi-ops-mcp-hub --service=auth

# Development mode (localhost APIs)
YIRIFI_API_KEY=your_key uvx yirifi-ops-mcp-hub --mode=dev

# HTTP transport (for remote deployment)
uvx yirifi-ops-mcp-hub --transport=http --port=5200
```

**Options:**
- `--service`: `all` (default), `auth`, or `reg`
- `--mode`: `dev` (localhost) or `prd` (remote, default)
- `--transport`: `stdio` (default) or `http`
- `--port`: HTTP port (default: 5200)

### Utility Commands

```bash
# List available tools
uvx yirifi-ops-mcp-hub list-tools

# Test API connection
uvx yirifi-ops-mcp-hub test-connection --service=auth

# Show OpenAPI spec
uvx yirifi-ops-mcp-hub show-spec --service=auth

# Check version
uvx yirifi-ops-mcp-hub --version
```

## Architecture

This package uses a tiered exposure system for safe AI access:

- **DIRECT**: Safe, frequent operations exposed as individual MCP tools
- **GATEWAY**: Admin/dangerous operations accessible via `{service}_api_call` gateway tool
- **EXCLUDE**: Internal endpoints never exposed

### Spec-Driven Catalog (v0.4.0+)

Endpoints can be configured via OpenAPI `x-mcp-*` extensions or override files:

| Extension | Type | Default | Description |
|-----------|------|---------|-------------|
| `x-mcp-tier` | `direct\|gateway\|exclude` | `gateway` | Exposure tier |
| `x-mcp-risk-level` | `low\|medium\|high` | `medium` | Risk classification |
| `x-mcp-name` | `string` | `operationId` | Override tool name |
| `x-mcp-description` | `string` | `summary` | Override description |

## Environment Variables

- `YIRIFI_API_KEY`: API key for authentication (required)
- `AUTH_SERVICE_API_KEY`: Service-specific fallback for auth
- `REG_SERVICE_API_KEY`: Service-specific fallback for reg

## License

Proprietary - Yirifi
