# fabric-mcp — aligned Equinix Fabric MCP server (self-hosted)

A local, self-hosted Python MCP server that reimplements the **contract** of the hosted
`mcp.equinix.com/fabric` server (109 tools, protocol-compatible) over the public Fabric REST v4
API — with **client-credentials** auth (no browser OAuth) and a **governance layer** that lets us
safely add destructive operations. Supersedes the fragile hosted-OAuth path (CIMD `invalid_request`,
Desktop timeouts, token-cache churn) and the old ungated `equinix-fabric-python` server.

## Why
- `mcp.equinix.com/fabric` is hosted + user-delegated OAuth → fights Claude Desktop's 60s timeout
  and Equinix's CIMD rejection. A local stdio server with client-credentials sidesteps all of it.
- Full control: our own codebase, our own extensions, **governed** delete/deprovision.

## Status (steps 1–3 done, no credentials needed)
- **Contract** (`contract/contract.json`) — 109 official tools + 3 governed extensions, each with
  `{authority, category, rest_hint, schema:pending, implemented_in_v1}`.
- **Gap map** (`contract/GAP.md`) — vs the old `equinix-fabric-mcp/server.py` (~15 covered, 94 to build).
- **Governance core** (`governance/gate.py`) — authority classifier + dry-run-before-write +
  confirm + destructive allow-list + two-key + protected-targets + audit. Self-tested.

## Architecture
```
Claude Desktop / LiteLLM ──(stdio MCP)──►  fabric-mcp (this server)
                                              │  client-credentials (no browser)
                                              ├─ governance/gate.py  (authority + approval + audit)
                                              └─ REST ──►  api.equinix.com/fabric/v4
```
Authority tiers: read-only = allowed+audited · write = dry-run→confirm · destructive = dry-run +
allow-list + two-key + protected-target deny.

## Remaining (needs credentials)
- **Step 4** — implement the 94 REST wrappers (read-only → write → governed destructive), filling
  per-tool input schemas from a fresh `tools/list` dump or the Fabric v4 OpenAPI spec.
- **Step 5** — wire into Claude Desktop (local stdio, the working path) + optional LiteLLM route;
  live-test with the fresh key.

## Credentials — drop point
This server authenticates with the **Fabric REST API** via OAuth2 **client-credentials**
(`https://api.equinix.com/oauth2/v1/token`, `grant_type=client_credentials`). Generate a fresh
API key pair in the Equinix portal (developer.equinix.com → your app → Consumer Key/Secret) and
put them in **`~/Development/Equinix/fabric-mcp/.env`** (gitignored):

```
EQUINIX_CLIENT_ID=<consumer key>
EQUINIX_CLIENT_SECRET=<consumer secret>
FABRIC_MCP_MODE=mock          # mock (default) | live
```
The server reads them from the environment only — never hardcoded, never committed. See `.env.example`.