Skip to main content
Glama
DittoFS control-plane API (read-only subset) MCP server

DittoFS control-plane API (read-only subset) MCP server

by Ankur1911
README.md
# DittoFS control-plane API (read-only subset) MCP server

Generated by openapi2mcp 0.1.0 from the DittoFS control-plane API (read-only subset) OpenAPI spec (10 tools).

## Run

```bash
cp .env.example .env     # then edit if the API needs credentials
uv run server.py         # speaks MCP over stdio
```

Set `API_TOKEN` in `.env`; it is sent as a bearer token.

## Connect a client

Add this to any MCP-compatible client (for example Cursor or VS Code), using the absolute path to this folder:

```json
{
  "mcpServers": {
    "dittofs-ops": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/this/folder", "server.py"]
    }
  }
}
```

The exact config file and key names differ by client; check your client's MCP documentation.

## Tools

| Tool | Request | Summary |
|---|---|---|
| `getHealth` | `GET /health` | Liveness probe for the control plane |
| `getReadiness` | `GET /health/ready` | Readiness probe (database reachable, adapters up) |
| `listShares` | `GET /api/v1/shares` | List all shares with usage, quota and enabled state |
| `getShareStatus` | `GET /api/v1/shares/{name}/status` | Health status of one share |
| `listShareQuotas` | `GET /api/v1/shares/{name}/quotas` | List quotas configured on a share |
| `listShareSnapshots` | `GET /api/v1/shares/{name}/snapshots` | List snapshots of a share |
| `getBlockstoreStats` | `GET /api/v1/blockstore/stats` | Block store statistics across all shares (cache and remote usage) |
| `listClients` | `GET /api/v1/clients` | List connected NFS and SMB clients |
| `listAdapters` | `GET /api/v1/adapters` | List protocol adapters (NFS, SMB) with running state, port and health |
| `listBlockStores` | `GET /api/v1/store/block` | List configured block stores |

## Configuration

See `.env.example`. Key settings: `API_BASE_URL`, `API_TIMEOUT`, `MAX_RESPONSE_CHARS`, `LOG_LEVEL`, `MCP_TRANSPORT`.

Logs go to stderr (stdout is reserved for the protocol).

## Status

Unofficial, read-only prototype. DittoFS does not publish an OpenAPI document yet, so `dittofs-openapi.yaml` is a hand-derived, 10-operation GET-only spec based on the control-plane router and handlers; it may drift from the real API. Calls were exercised only against the local mock in `mock_dittofs.py` (`uv run mock_dittofs.py`), not against a real `dfs` server. Write operations are intentionally left out. Related issue: https://github.com/cubbit/dittofs/issues/4301

Licence: MIT.