@derive-ltd/reify

Read-only tooling for exploring Reify projects. The package ships two binaries:

• reify-mcp — MCP server (stdio transport) for Claude Desktop and other local MCP clients.
• reify — command-line client. Thin wrapper that calls the same MCP tools via the remote /mcp endpoint, so every MCP tool becomes a CLI command automatically.

Both talk to a running Reify instance over HTTPS with a Bearer token (either a personal API token or an OAuth-issued access token).

CLI quick start

export REIFY_API_URL=https://reify.airgen.studio
export REIFY_API_TOKEN=rfy_...

npx @derive-ltd/reify reify --help                # show commands
npx @derive-ltd/reify reify list-projects
npx @derive-ltd/reify reify get-project se-eeg-accessibility-buggy
npx @derive-ltd/reify reify get-checklist se-eeg-accessibility-buggy
npx @derive-ltd/reify reify get-diagram se-eeg-accessibility-buggy \
    --type=bdd --scope="Power Subsystem"

The command name is the MCP tool name without the reify_ prefix and with underscores as hyphens — e.g. reify_list_projects → reify list-projects. Required arguments can be passed as positionals in schema order (reify get-project <slug>), or as --flag=value pairs; flags override positionals.

reify list-tools prints every tool with its input schema, fetched live from /mcp. If you add a new tool server-side, it shows up in the CLI with no code changes.

What it exposes

All read-only. The CLI talks to the deployed Reify HTTP API at /mcp and exposes whatever tools that endpoint advertises (currently 19); the local stdio server bundled in this package is a 15-tool subset. The table below covers the stdio subset; run reify list-tools for the live server list.

| Tool | What it does | |---|---| | reify_list_projects | List projects the token can access | | reify_get_project | Project detail + workspace state | | reify_get_stats | Fact/req/link/view counts by type | | reify_get_sysml | Full project SysML (canonical or workspace) | | reify_list_sysml_sections | Section index | | reify_get_sysml_section | Body of one section | | reify_list_views | All views (optional viewpoint filter) | | reify_get_view_sysml | SysML scoped to one view | | reify_get_view_diagram | Structured diagram JSON for a view | | reify_get_diagram | Structured diagram JSON by type | | reify_list_requirements | AIRGen requirements | | reify_list_trace_links | AIRGen trace links | | reify_query_facts | Raw substrate fact query | | reify_workspace_state | Editor workspace state + drift flag | | reify_parse_sysml | Stateless SysML parser |

The deployed /mcp endpoint additionally exposes reify_get_agent_session, reify_list_agent_sessions, reify_get_checklist, and reify_get_project_ast. These are reachable from the reify CLI (which calls /mcp directly) but not from the bundled stdio server until the stdio tool list is synced.

All writes — commit, workspace edits, view CRUD, agent triggers — stay behind the UI-authenticated routes. This package deliberately has no path to mutate state.

Prerequisites

1. A running Reify server with the v1 API deployed.

2. A bearer token for a user with access to the projects you want to explore. Generate one on the Reify server:

   cd /path/to/reify/app
   node --import tsx/esm scripts/generate-api-token.ts github:12345 "Claude Desktop"

   The plaintext token prints once. Store it somewhere safe.

Install into Claude Desktop

Add an entry to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "reify": {
      "command": "npx",
      "args": ["-y", "@derive-ltd/reify"],
      "env": {
        "REIFY_API_URL": "https://reify.airgen.studio",
        "REIFY_API_TOKEN": "rfy_paste_your_token_here"
      }
    }
  }
}

Restart Claude Desktop. The fifteen stdio tools should appear in the tool picker under the reify server.

Usage examples

Once wired in, you can ask Claude Desktop things like:

• "What Reify projects do I have access to?"
• "Summarize the EEG Accessibility Buggy project — subsystems, hazards, requirements count."
• "Show me the Power Subsystem BDD view as a diagram."
• "Which trace links touch SYS-REQ-001?"
• "Parse this SysML snippet and tell me what substrate facts it would produce."
• "Is there an uncommitted workspace for se-eeg-accessibility-buggy, and has it drifted?"

Environment variables

| Var | Required | Purpose | |---|---|---| | REIFY_API_URL | yes | Base URL of the Reify instance (e.g. https://reify.airgen.studio). Trailing slash is tolerated. | | REIFY_API_TOKEN | yes | Bearer token generated via generate-api-token.ts. Read scope is sufficient. |

Running locally

cd packages/reify-mcp
npm run build
REIFY_API_URL=https://reify.airgen.studio REIFY_API_TOKEN=rfy_... node dist/index.js

The server speaks MCP over stdio — not meant to be used interactively on a terminal. The bin field registers reify-mcp so once the package is published npx -y @derive-ltd/reify works from any Claude Desktop config.

Troubleshooting

• "REIFY_API_URL is not set" — the env var is missing from Claude Desktop's config. Make sure both REIFY_API_URL and REIFY_API_TOKEN are inside the env object, not at the top level.
• 401 Unauthorized — the token is wrong or was revoked on the server. Generate a fresh one with generate-api-token.ts.
• 403 Forbidden — the token is valid but its user does not have access to the requested project. Edit /root/derive/data/permissions.json on the Reify server to grant it.
• Tools don't appear in Claude Desktop — check the logs (~/Library/Logs/Claude/mcp-*.log on macOS). A common cause is a bad path to npx — try an absolute path in command.