Metadata-Version: 2.5
Name: colabhive-mcp
Version: 0.2.0
Summary: Model Context Protocol server for ColabHive — expose LLMs, specialists, tools, and your trained models to any MCP client.
Project-URL: Homepage, https://docs.colabhive.com/mcp
Project-URL: Documentation, https://docs.colabhive.com/mcp
Project-URL: Repository, https://github.com/colabhive/colabhive-api
Project-URL: Issues, https://github.com/colabhive/colabhive-api/issues
Project-URL: Changelog, https://github.com/colabhive/colabhive-api/blob/main/packages/mcp-server/CHANGELOG.md
Author-email: ColabHive <engineering@colabhive.com>
License: MIT
Keywords: agent,ai,colabhive,llm,mcp,model-context-protocol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: keyring>=24
Requires-Dist: mcp<2.0,>=0.9
Requires-Dist: pydantic>=2.6
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: http
Requires-Dist: fastapi>=0.110; extra == 'http'
Requires-Dist: sse-starlette>=2.0; extra == 'http'
Requires-Dist: uvicorn[standard]>=0.27; extra == 'http'
Description-Content-Type: text/markdown

# colabhive-mcp

**Status:** scaffold / not yet implemented. See [`docs/plans/PLAN-mcp-layer-2026-05-22.md`](../../docs/plans/PLAN-mcp-layer-2026-05-22.md).

Model Context Protocol (MCP) server that exposes every ColabHive model — LLMs, specialists, tools, your trained models — to any MCP-compatible AI client (Claude Desktop, Claude Code, Cursor, n8n, …).

User-facing docs: <https://docs.colabhive.com/mcp>

---

## Roadmap

| Phase | Deliverable | Status |
|---|---|---|
| F0 | DB manifest columns + `/mcp/manifest` endpoint in `builder-gateway` | 🟡 in progress |
| F1 | This package, published to PyPI | 🟡 in progress |
| F2 | OAuth 2.1 device flow + rate limiting | ⬜ pending |
| F3 | Client integration docs + screenshots | ⬜ pending |
| F4 | Hosted SaaS (`mcp.colabhive.com`) + marketplace | ⬜ pending |

---

## Package layout (planned)

```
packages/mcp-server/
├── pyproject.toml
├── README.md                                  # this file
├── LICENSE                                    # MIT
├── src/
│   └── colabhive_mcp/
│       ├── __init__.py
│       ├── __main__.py                        # entry: `python -m colabhive_mcp`
│       ├── cli.py                             # argparse, sub-commands: serve, test, config, login, logout
│       ├── client.py                          # HTTP client for /api/builder/v1/{actions,mcp,invocations}
│       ├── manifest.py                        # ETag cache, refresh, schema validation
│       ├── auth.py                            # API key + OAuth device flow + keychain
│       ├── server_stdio.py                    # MCP stdio transport
│       ├── server_http.py                     # MCP HTTP/SSE transport (FastAPI)
│       ├── filters.py                         # allow/deny tools + kinds + stability
│       ├── invoke.py                          # sync/async glue, polling
│       ├── config.py                          # env + flag + TOML resolver
│       └── logging.py                         # structured JSON logger with redaction
├── tests/
│   ├── unit/
│   │   ├── test_manifest_cache.py
│   │   ├── test_filters.py
│   │   ├── test_invoke_sync_async.py
│   │   └── test_config_resolver.py
│   └── e2e/
│       └── test_full_flow.py                  # gated on COLABHIVE_API_KEY_STAGING
├── docs/
│   └── jsonrpc-examples/                      # captured frames for debugging
└── Dockerfile                                  # for HTTP/SSE deploy mode
```

---

## Install (when published)

```bash
# Recommended (no global Python needed)
uvx colabhive-mcp@latest

# Or pipx
pipx install colabhive-mcp

# Or pip
pip install colabhive-mcp
```

---

## Quickstart (when published)

```bash
export COLABHIVE_API_KEY=hive_sk_xxx
colabhive-mcp test
```

Then add to your MCP client:

```json
{
  "mcpServers": {
    "colabhive": {
      "command": "uvx",
      "args": ["colabhive-mcp@latest"],
      "env": { "COLABHIVE_API_KEY": "hive_sk_xxx" }
    }
  }
}
```

See [user docs](https://docs.colabhive.com/mcp) for full guides per client.

---

## Dev (when scaffolding lands)

```bash
# From repo root
uv pip install -e packages/mcp-server[dev]

# Run unit tests
pytest packages/mcp-server/tests/unit

# Run E2E against staging (needs API key)
COLABHIVE_API_KEY_STAGING=hive_sk_xxx \
COLABHIVE_API_URL=https://api.staging.colabhive.com \
  pytest packages/mcp-server/tests/e2e

# Run manually in stdio mode
COLABHIVE_API_KEY=hive_sk_xxx python -m colabhive_mcp

# Run in HTTP/SSE mode
COLABHIVE_API_KEY=hive_sk_xxx python -m colabhive_mcp serve --port 8765
```

---

## Dependencies (planned)

| Package | Why |
|---|---|
| `mcp >= 0.9` | Anthropic's MCP Python SDK — protocol layer. Pinned tight in F1; we wrap the subset we use behind an interface so we can swap if the SDK shifts. |
| `httpx >= 0.27` | Async HTTP client for talking to api.colabhive.com |
| `pydantic >= 2.6` | Manifest validation, config schemas |
| `tomli` / `tomllib` | Config file parsing |
| `keyring >= 24` | Keychain for OAuth tokens (Linux/macOS/Windows backends) |
| `fastapi >= 0.110` + `uvicorn >= 0.27` | HTTP/SSE transport (optional, `[http]` extra) |
| `pytest` + `pytest-asyncio` + `respx` | Tests (dev only) |

---

## Compliance with CLAUDE.md rules

- **REGLA #0** — No engine names hardcoded. Tool `kind` is derived from the manifest, which comes from `_compute_kind()` in `builder-gateway`. This package never compares engine strings.
- **REGLA #1** — DB is the only source of truth. Manifests are fetched, not invented. Missing manifest field → missing in MCP output, no defaults.
- **REGLA #2** — `mcp_stability` reflects `lifecycle_status`. Filtering by `--stability stable` excludes `candidate` (= `beta`).
- **REGLA #4** — Publish to PyPI with checksum + tag + `latest` version follows the same rigor as wheel deploys.
- **REGLA #7** — E2E tests cover the production-critical models listed in the master plan.

---

## License

MIT — see [`LICENSE`](LICENSE).

---

## Links

- 📖 Docs: <https://docs.colabhive.com/mcp>
- 🛠 Master plan: [`docs/plans/PLAN-mcp-layer-2026-05-22.md`](../../docs/plans/PLAN-mcp-layer-2026-05-22.md)
- 🐛 Issues: <https://github.com/colabhive/colabhive-api/issues> (label `mcp`)
- 🔒 Security: `security@colabhive.com` (see top-level `SECURITY.md`)
