# TraceRTM MCP/CLI/API Capability Matrix (Offline + Online)

## Scope
This doc maps **MCP**, **CLI**, and **API** capabilities in both **offline** and **online** modes, and clarifies that each client is optional.

## Key Principles
- **Offline-first:** Local DB is primary for local operations.
- **Online optional:** Sync/API only required for remote collaboration.
- **Client optionality:** MCP and CLI can be used independently (or together).
- **Auth separation:** MCP auth does **not** depend on CLI state.

## Clients at a Glance

### MCP (FastMCP server)
- **Entry:** `python -m tracertm.mcp` or `rtm mcp start`
- **Auth:** WorkOS AuthKit JWT (OAuth), optional static dev API keys
- **Offline:** Full CRUD + analysis via local DB
- **Online:** Sync via API if configured

### CLI (Typer + Rich)
- **Entry:** `rtm <command>`
- **Auth:** WorkOS AuthKit device flow
- **Offline:** Full CRUD + analysis via local DB
- **Online:** Sync/pull/push via API

### API
- **Local API client:** `src/tracertm/api/client.py` (DB-backed)
- **Remote sync client:** `src/tracertm/api/sync_client.py` (HTTP)
- **Auth:** Bearer token (AuthKit OAuth)

## Auth Matrix

| Client | Offline | Online | Auth Method |
| --- | --- | --- | --- |
| MCP | ✅ | ✅ | AuthKit JWT (OAuth) or static dev keys |
| CLI | ✅ | ✅ | AuthKit device flow |
| API | n/a | ✅ | Bearer token (AuthKit OAuth) |

## Storage & State

### Per-user system dir
- `~/.tracertm/`
  - `config.yaml` (global config)
  - `tracertm.db` (local DB)
  - `mcp/token.json` (optional MCP token storage)

### Per-project dir (repo)
- `.tracertm/`
  - `project.yaml` (project metadata)
  - `specs/` (optional exports)
  - `.gitignore` (ignore local state/cache)

## MCP Tool Surface (Unified/Param + Specs)

**Param tools (canonical/atoms-style):**
- `project_manage`
- `item_manage`
- `link_manage`
- `trace_analyze`
- `graph_analyze`
- `spec_manage`
- `quality_analyze`
- `config_manage`
- `sync_manage`
- `export_manage`
- `import_manage`
- `ingest_manage`
- `backup_manage`
- `watch_manage`
- `db_manage`
- `agents_manage`
- `progress_manage`
- `saved_queries_manage`
- `test_manage`
- `tui_manage`
- `benchmark_manage`
- `chaos_manage`
- `design_manage`

**Spec tools (domain-specific):**
- `create_adr`, `list_adrs`
- `create_contract`
- `create_feature`, `create_scenario`
- `analyze_quality`

## CLI Command Surface (Categories)

- **Auth:** `auth login|logout|status`
- **Project:** `project`, `init`
- **Items:** `item`
- **Links:** `link`
- **Query/Search:** `query`, `search`, `saved-queries`, `drill`
- **Views/UI:** `view`, `dashboard`, `tui`
- **Progress/History:** `progress`, `history`, `state`
- **Sync/Watch:** `sync`, `watch`
- **Import/Export/Backup:** `import`, `export`, `backup`, `ingest`
- **DB/Config:** `db`, `config`, `migrate`
- **Quality/Test:** `test`
- **Ops:** `benchmark`, `chaos`, `agents`, `design`
- **MCP:** `mcp start|tools|resources|config`
- **Shortcuts:** `mvp-shortcuts`

## Capability Matrix (Offline vs Online)

| Capability | MCP Offline | MCP Online | CLI Offline | CLI Online | API |
| --- | --- | --- | --- | --- | --- |
| Project CRUD | ✅ | ✅ | ✅ | ✅ | ✅ (sync) |
| Item CRUD | ✅ | ✅ | ✅ | ✅ | ✅ (sync) |
| Link CRUD | ✅ | ✅ | ✅ | ✅ | ✅ (sync) |
| Trace matrix | ✅ | ✅ | ✅ | ✅ | ✅ |
| Impact analysis | ✅ | ✅ | ✅ | ✅ | ✅ |
| Graph analysis | ✅ | ✅ | ✅ | ✅ | ✅ |
| Specs (ADR/BDD/Contract) | ✅ | ✅ | ✅* | ✅* | ✅ |
| Quality analysis | ✅ | ✅ | ✅* | ✅* | ✅ |
| Export | ✅ | ✅ | ✅ | ✅ | ✅ |
| Import | ✅ | ✅ | ✅ | ✅ | ✅ |
| Backup | ✅ | ✅ | ✅ | ✅ | ✅ |
| Watch/file ingest | ✅ | ✅ | ✅ | ✅ | ✅ |
| Sync/pull/push | ⚠️ | ✅ | ⚠️ | ✅ | ✅ |
| Auth | ✅ (dev key) | ✅ (OAuth) | ✅ (device) | ✅ (device) | ✅ (OAuth) |

* CLI uses API-backed services for some spec-quality routes depending on build; MCP supports them directly.

## Offline + Online Flow

### Offline-only (MCP or CLI)
1. Local DB initialized in `~/.tracertm/`
2. Create projects/items/links/specs
3. Export/backup as needed

### Online Sync (optional)
1. Authenticate (CLI device flow or MCP OAuth)
2. Configure `api_url` and token
3. Run sync (push/pull changes)

## Notes
- MCP does **not** require CLI tokens; CLI token sync is optional and manual.
- Dev API keys are supported for MCP in non-production environments.
- Remote MCP deploy uses the same AuthKit OAuth bearer tokens as the API.
