npm package: @first-to-fly/orchestrator-mcp
Description: MCP server for FirstToFly Orchestrator - persistent memory for Claude Code
Latest version: 0.7.3

# @first-to-fly/orchestrator-mcp

Persistent, structured memory for Claude Code via MCP.

Claude Code has two built-in memory mechanisms — `CLAUDE.md` (static instructions) and auto memory (a 200-line markdown notepad). Both are local files tied to one machine with no search, no structure, and no way to share context between developers or CI agents.

Orchestrator adds a third layer: a database-backed memory system with typed entities, relationships, relevance-scored recall, and lifecycle management — accessible from any environment via API key.

## What it does

- **Recalls past decisions** so you don't re-explain architecture every session
- **Remembers error fixes** so the same bug doesn't get debugged twice
- **Builds project context** — agents understand what was built and why
- **Stores patterns** with examples so agents follow your conventions
- **Manages a work queue** so webhook events become tasks agents pick up
- **Tracks costs** per session so you know what you're spending

## Quick Start

1. **Sign up** at [orchestrator.firsttofly.com](https://orchestrator.firsttofly.com) and create a project
2. **Generate an API key** from the project's Setup page
3. **Run the init command** in your project directory:

```bash
npx @first-to-fly/orchestrator-mcp@latest init
```

This will:

- Prompt for your API URL, key, and project slug
- Validate the API key against the server
- Create `.mcp.json` with the MCP server config
- Append the orchestrator protocol to `CLAUDE.md`
- Set up the PreCompact hook in `.claude/settings.local.json`
- Seed built-in recipes

4. **Start a new Claude Code session** — the orchestrator auto-connects

## Two MCP Packages

The orchestrator is split into two MCP servers to keep the agent's tool list focused:

| Package                                | Tools | Purpose                                       |
| -------------------------------------- | ----- | --------------------------------------------- |
| `@first-to-fly/orchestrator-mcp`       | 12    | Daily agent use — recall, store, specs, queue |
| `@first-to-fly/orchestrator-mcp-admin` | 11    | Management — scaffold, bulk ops, prune, audit |

Most projects only need the agent MCP. Add the admin MCP when you need to scaffold a project, bulk-seed knowledge, manage the work queue, or audit entity history.

## Agent Tools (12)

### Recall

| Tool          | What it does                                                                                                                         |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `recall`      | Retrieve relevant context for a task. Hybrid scoring with tiered rendering (`mode: "context"`) or keyword search (`mode: "search"`). |
| `get_entity`  | Fetch full entity content, metadata, and attachments by type and ID.                                                                 |
| `check_error` | Check if a similar error was seen before. May return a known fix.                                                                    |

### Store

| Tool                 | What it does                                                                                                       |
| -------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `store_entity`       | Create or update a knowledge entity (single or array via `entities`). Deduplicates by type+name, or updates by ID. |
| `store_relationship` | Link two entities with a typed relationship (single or array via `relationships`).                                 |

### Sessions

| Tool                   | What it does                                    |
| ---------------------- | ----------------------------------------------- |
| `save_session_summary` | Save a structured handoff for the next session. |

### Specs

| Tool                 | What it does                                                             |
| -------------------- | ------------------------------------------------------------------------ |
| `compose_spec`       | Compose a spec document from a root requirement (omit ID to list roots). |
| `analyze_spec`       | Review spec quality — conflicts, ambiguities, gaps, suggestions.         |
| `save_smoothed_spec` | Upload a smoothed specification document.                                |

### Recipes

| Tool     | What it does                                                |
| -------- | ----------------------------------------------------------- |
| `recipe` | Get a recipe by name, or list all recipes if no name given. |

### Queue

| Tool              | What it does                                                   |
| ----------------- | -------------------------------------------------------------- |
| `claim_next_task` | Claim the highest-priority unclaimed work item from the queue. |
| `resolve_task`    | Mark a work item as completed or failed.                       |

## Hook: PreCompact

The `init` command sets up a single hook in `.claude/settings.local.json`:

- **PreCompact**: Before Claude Code compresses context, this hook saves a session summary to the orchestrator so context survives compression.

## Entity Types

| Type          | Purpose                                                       | Stale after | TTL       | Protected |
| ------------- | ------------------------------------------------------------- | ----------- | --------- | --------- |
| `module`      | Code areas and architecture                                   | 180 days    | Permanent | No        |
| `decision`    | Architectural choices with rationale, alternatives, tradeoffs | 365 days    | Permanent | Yes       |
| `pattern`     | Reusable approaches with example files and anti-patterns      | 365 days    | Permanent | Yes       |
| `requirement` | Specs and requirements with acceptance criteria               | 365 days    | Permanent | Yes       |
| `error`       | Bug + fix pairs with stack traces and root cause              | 60 days     | 90 days   | No        |
| `task`        | Completed work with files modified and outcome                | 30 days     | 90 days   | No        |
| `observation` | Quick insights and notes                                      | 60 days     | 90 days   | No        |
| `session`     | Structured handoff summaries between sessions                 | 180 days    | 180 days  | Yes       |

Protected types are never auto-pruned by `prune_stale`.

## CLAUDE.md Protocol

The `init` command appends this protocol to your `CLAUDE.md`:

```markdown
## Orchestrator Protocol

### Retrieve Knowledge First

- `recall` — start here: assembles relevant entities with tiered rendering (mode: context) or keyword search (mode: search)
- `get_entity` for full content of a specific entity
- `check_error` before debugging — a known fix may exist

### Living Specifications

- `compose_spec` — read composed specs from requirement entities (omit ID to list roots)
- `analyze_spec` — review spec quality before smoothing
- `save_smoothed_spec` — cache a polished version for future sessions

### Store Significant Knowledge

Store what compounds across sessions — not everything, just what matters:

- **Decisions**: architectural choices with rationale (the WHY)
- **Patterns**: reusable approaches worth repeating, with anti-patterns
- **Errors**: bugs with root cause + fix, so the same mistake isn't debugged twice
- **Requirements**: specs that define what to build (link via `part_of` to a root)

`store_entity` handles both create (by type+name) and update (by id).

### Relationships & Sessions

- Link entities: `depends_on`, `supersedes`, `caused_by`, `implements`, `part_of`, `relates_to`
- `save_session_summary` when ending with meaningful work worth preserving
```

## Built-in Recipes

| Recipe                | Triggers                                             | What it does                                                           |
| --------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------- |
| `debug-error`         | debug, error, fix, bug                               | Guided error debugging workflow: check → investigate → store → resolve |
| `new-module`          | new module, create module, scaffold                  | Scaffold a new backend module following conventions                    |
| `session-handoff`     | end session, wrap up, done for today                 | Template for saving a complete session summary                         |
| `knowledge-capture`   | learned, discovery, insight, remember                | Decision tree for choosing the right entity type                       |
| `bootstrap-knowledge` | bootstrap, scaffold, index project                   | Comprehensive codebase analysis and knowledge indexing                 |
| `investigate-area`    | how does, understand, explore                        | Systematic approach to understanding a code area                       |
| `capture-spec`        | spec, requirement, feature, user story               | Capture requirements as versioned, structured entities                 |
| `implement-from-spec` | implement spec, implement requirement, build feature | Implement a feature by reviewing its stored requirements first         |

## Manual Setup

If you prefer to configure manually, create these files in your project root.

### .mcp.json

```json
{
  "mcpServers": {
    "orchestrator": {
      "command": "npx",
      "args": ["-y", "@first-to-fly/orchestrator-mcp@latest"],
      "env": {
        "ORCHESTRATOR_API_URL": "https://orchestrator.firsttofly.com/api/v1",
        "ORCHESTRATOR_API_KEY": "ftfo_your_key_here",
        "ORCHESTRATOR_PROJECT": "your-project-slug"
      }
    }
  }
}
```

### Environment Variables

| Variable               | Description                                                      | Required |
| ---------------------- | ---------------------------------------------------------------- | -------- |
| `ORCHESTRATOR_API_URL` | API endpoint (e.g. `https://orchestrator.firsttofly.com/api/v1`) | Yes      |
| `ORCHESTRATOR_API_KEY` | Project API key (starts with `ftfo_`)                            | Yes      |
| `ORCHESTRATOR_PROJECT` | Project slug                                                     | Yes      |

## Works Everywhere

| Environment     | How it connects                    | What it gets                                                              |
| --------------- | ---------------------------------- | ------------------------------------------------------------------------- |
| Local developer | MCP server in Claude Code settings | Full memory — recall, store, queue, recipes                               |
| CI agent        | Same MCP config with API key       | Same memory — PR review agents recall project patterns and past decisions |
| Team member     | Shared project, own API key        | Shared knowledge — one developer stores a decision, another recalls it    |

## Links

- [Web App](https://orchestrator.firsttofly.com)
- [GitHub](https://github.com/first-to-fly/firsttofly-orchestrator)
- [Issues](https://github.com/first-to-fly/firsttofly-orchestrator/issues)