# outflow-mcp

An MCP (Model Context Protocol) server that exposes a live Outflow architecture
graph as context for AI coding agents — Claude Code, Claude Desktop, or any
other MCP-compatible client. Lets an agent ask "what does this file depend
on", "what breaks if I change this", or "did my last batch of edits introduce
a circular dependency" against your workspace's real, currently-live graph.

It's a thin client over Outflow's existing `/api/v1` REST API and the
workspace graph routes — no graph logic 
is duplicated here.

> This package is developed inside the main Outflow monorepo but published
> from a standalone public mirror: **https://github.com/laurells/outflow-mcp**
> — that's the repo MCP registries/crawlers point at, and where `npm publish`
> runs from. Changes here get synced there before each release.

## Setup

1. **Create an API key** for the workspace you want to expose. In Outflow,
   go to workspace settings → API Keys → create one. The raw key (`ofk_...`)
   is shown once — copy it.
2. **Find your workspace ID** — it's in the workspace URL
   (`.../workspace/<id>/...`) or workspace settings.
3. **Build the server**:
   ```bash
   cd packages/mcp-server
   npm install
   npm run build
   ```
4. **Add it to your MCP client config.** For Claude Code, add to your MCP
   settings (`claude mcp add` or the equivalent config file):
   ```json
   {
     "mcpServers": {
       "outflow": {
         "command": "node",
         "args": ["/absolute/path/to/outflow/packages/mcp-server/dist/index.js"],
         "env": {
           "OUTFLOW_BASE_URL": "https://your-outflow-domain.com",
           "OUTFLOW_API_KEY": "ofk_...",
           "OUTFLOW_WORKSPACE_ID": "your-workspace-id"
         }
       }
     }
   }
   ```
   For local development, `OUTFLOW_BASE_URL` defaults to `http://localhost:3000`
   if omitted.

## Tools

| Tool | Use it to ask |
|---|---|
| `find_node` | Is this file tracked? What's its ID? |
| `list_nodes` | What's deprecated / low health / a given type? |
| `get_dependencies` | What does this file rely on? |
| `get_impact` | What breaks if I change this file? (blast radius) |
| `find_path` | How are these two files connected? |
| `get_architecture_health` | What's the overall health grade and at-risk nodes? |
| `find_architecture_smells` | Any circular deps, god nodes, or dead code right now? |
| `get_architecture_graph` | Give me the whole graph at a zoom level. |
| `get_last_session_recap` | What happened in my last coding session? |

All tools that take a `path` accept a partial match (e.g. `"ApiClient"` will
match `src/ApiClient.ts`) — you never need to know Outflow's internal
`file::`/`method::` ID format. An ambiguous partial match returns an error
listing the candidates instead of guessing.

## Notes

- This package is standalone — it is never bundled into `server/` or `web/`,
  and has no build-time dependency on them. It only talks to a running
  Outflow instance over HTTP using an API key, so it works equally well
  pointed at localhost or a deployed instance.
- `get_dependencies`/`get_impact` and `find_architecture_smells`/`find_path`
  call workspace graph routes that (as of this package's introduction) were
  extended to accept `Authorization: Bearer ofk_...` alongside the existing
  cookie-session auth — see `server/src/graph/pathRouter.ts` and
  `smellsRouter.ts`.