delphicourier

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="media/logo-dark.svg"> <img alt="DelphiCourier MCP" src="media/logo-light.svg" width="120"> </picture> </p> <h1 align="center">DelphiCourier MCP</h1> <p align="center"> <em>Scope first, intelligence second<br> We shrink context before you pay for expensive reasoning-model tokens.</em> </p> <p align="center"> <a href="https://github.com/kccarlos/delphicourier/actions/workflows/ci.yml"><img src="https://github.com/kccarlos/delphicourier/actions/workflows/ci.yml/badge.svg" alt="CI Status"></a> <a href="https://github.com/kccarlos/delphicourier/releases/latest"><img src="https://img.shields.io/github/v/release/kccarlos/delphicourier" alt="Latest Release"></a> <a href="https://github.com/kccarlos/delphicourier/blob/main/LICENSE"><img src="https://img.shields.io/github/license/kccarlos/delphicourier" alt="License"></a> </p> DelphiCourier is an MCP server that acts as a strict logistics layer between your local coding agent and the smartest, most expensive AI models. Directly sending an entire repository to a strong reasoning model is expensive, noisy, and hard to reproduce. DelphiCourier solves this by letting your CLI agent narrow context down to a precise recipe of files, diffs, refs, and line ranges. DelphiCourier then deterministically shrinks that context to fit a strict token budget and couriers it to the model. If Oracle answers the hard questions, DelphiCourier makes sure you are asking the right question with the exact right evidence. <a id="table-of-contents"></a> ## Table of Contents - [Table of Contents](#table-of-contents) - [Product Overview](#product-overview) - [The Intelligence Gap \& The "Agent Chatter" Tax](#the-intelligence-gap--the-agent-chatter-tax) - [The Stack: Where DelphiCourier Fits](#the-stack-where-delphicourier-fits) - [Why the Name](#why-the-name) - [What DelphiCourier Actually Does](#what-delphicourier-actually-does) - [Current MCP Tool Surface](#current-mcp-tool-surface) - [Getting Started](#getting-started) - [Prerequisites](#prerequisites) - [Required Tools](#required-tools) - [External Runtime Dependencies (Profile-Dependent)](#external-runtime-dependencies-profile-dependent) - [Optional but Recommended](#optional-but-recommended) - [Quick Start (API-Only Path)](#quick-start-api-only-path) - [1. Build and Configure](#1-build-and-configure) - [2. Run a Dry-Run Smoke Test](#2-run-a-dry-run-smoke-test) - [3. Run a Live API Call](#3-run-a-live-api-call) - [Running as an MCP Server](#running-as-an-mcp-server) - [Local Stdio Server](#local-stdio-server) - [⚠️ Common Gotcha: Host-Managed Environment](#️-common-gotcha-host-managed-environment) - [Engine Profiles](#engine-profiles) - [Browser Profile Setup Notes](#browser-profile-setup-notes) - [Configuration Resolution](#configuration-resolution) - [Development \& Operations](#development--operations) - [Development and Verification](#development-and-verification) - [Project Scripts](#project-scripts) - [Required Quality Gates](#required-quality-gates) - [Publishing \& Auto Release](#publishing--auto-release) - [What This Pipeline Does](#what-this-pipeline-does) - [One-Time Setup](#one-time-setup) - [How A Release Is Triggered](#how-a-release-is-triggered) - [Run with npx (No Install)](#run-with-npx-no-install) - [Dependency Model](#dependency-model) - [Docker Workflow (Recommended)](#docker-workflow-recommended) - [Troubleshooting](#troubleshooting) - [Reference](#reference) - [Project Layout](#project-layout) - [Acknowledgments](#acknowledgments) <a id="product-overview"></a> ## Product Overview <a id="intelligence-gap"></a> ### The Intelligence Gap & The "Agent Chatter" Tax In autonomous coding tools like Claude Code or Codex, access to top-tier reasoning models can vary by plan, environment, and host integration. Even when access exists, standard agents tend to send a "dump" of their work history to the model when asking for help. This includes redundant `git status` checks, massive `grep` outputs, tool-calling JSON blocks, and the agent's internal monologue. This "Agent Chatter" creates noise, dilutes the model's focus, and wastes expensive tokens. **DelphiCourier acts as a context wash.** It takes the messy exploration done by your agent and distills it into a "Pure Context" delivery. DelphiCourier stops your strongest model from wasting tokens on irrelevant code by delivering only the slices that matter. The context is stripped of agentic tool-calling chatter and preserved as focused code evidence plus minimal deterministic metadata. - **Agent-Driven Scope**: Your agent explicitly chooses what to include (`file_chunk`, `diff_hunk`, line ranges, refs). - **Granular Context Control**: Send only specific files, diffs, and code ranges. - **Deterministic Budgeting**: Predictable token estimation with an auditable shrink trace. No silent truncation surprises. - **Engine Abstraction + Fallback**: Put browser Oracle and API engines behind one MCP tool contract. - **Observable Runs**: Stable run IDs, attempt logs, token reports, and structured artifacts. ```mermaid flowchart LR A["CLI Agent Model<br/>Cheaper and good at agentic task <br/> e.g. GPT 5.3 Codex"] -->|"Explores Repo<br/>Generates Recipe"| B("DelphiCourier<br/>The Context Wash") B -->|"Strips Tool Logs<br/>Enforces Budget"| C{"Clean Code<br/>Context"} C -->|"Couriers Payload"| D["Oracle Model<br/>Best in reasoning and server side search but expensive <br/> e.g. GPT 5.2 Pro"] D -->|"Structured<br/>Guidance"| A ``` <a id="the-stack"></a> ### The Stack: Where DelphiCourier Fits | Component | Role | Responsibility | | --- | --- | --- | | **CLI Agent** | The Explorer | Explores the repo, runs `git`, and decides what matters by writing a context recipe. | | **DelphiCourier MCP** | The Courier | Validates the recipe, enforces strict token budgets, and handles engine fallback/retry behavior. | | **Oracle Engine** | The Brain | Receives a clean, token-budgeted prompt, reasons deeply, and returns structured guidance. | <a id="why-the-name"></a> ### Why the Name - `Delphi`: a nod to the ancient Greek oracle at Delphi. - `Courier`: this tool transports the right evidence to the oracle, not the whole codebase. Short version: DelphiCourier is the logistics layer between your CLI agent and the reasoning engine. <a id="what-delphicourier-does"></a> ### What DelphiCourier Actually Does DelphiCourier scopes context across **3 dimensions** before calling a model: 1. **Path scope (where)**: which files/paths are included. 2. **Revision scope (when)**: which refs/diffs are included (`ref`, `base_ref`, `head_ref`, `diff_hunk`). 3. **Range scope (how much)**: which exact line ranges and priority levels are included (`start_line`, `end_line`, `context_rank`). Then it runs the execution pipeline: 1. Validates a recipe of repo context (`file_chunk`, `diff_hunk`) 2. Builds a token-budgeted prompt 3. Calls one or more configured engines (with fallback/retries) 4. Returns structured guidance plus run diagnostics/artifacts <a id="mcp-tool-surface"></a> ### Current MCP Tool Surface DelphiCourier currently exposes these MCP tool endpoints: | MCP Tool | Purpose | Typical Use | | --- | --- | --- | | `get_recipe_schema` | Get the recipe format required by `consult_oracle` (schema + examples). | Use only when constructing or fixing a recipe payload. | | `consult_oracle` | Primary Oracle analysis entrypoint that reads a question + recipe and returns structured guidance with evidence and context requests. | Use proactively for impact analysis, regression risk review, invariant validation, commit/PR semantic review, and cross-module changes; prefer over manual inspection when >1 file is involved. | | `get_config_summary` | Get active Oracle config and available engine/budget profiles. | Use before `consult_oracle` when token budget or profile selection is uncertain. | For full architecture details, contract schemas, and Ralph-loop planning context, read `tech_spec.md`. <a id="getting-started"></a> ## Getting Started <a id="prerequisites"></a> ### Prerequisites <a id="required-tools"></a> #### Required Tools - `git` (DelphiCourier reads repo content through git refs) - `node` 22+ - `pnpm` 10+ (Corepack recommended) - `jq` (used by `scripts/pre-commit-checks.sh`) <a id="external-runtime-deps"></a> #### External Runtime Dependencies (Profile-Dependent) - OpenAI Responses API engine: - requires `OPENAI_API_KEY` - ChatGPT browser engine: - uses `npx -y @steipete/oracle` - may require one-time manual browser login - Optional packing/compression integration: - uses `npx -y repomix` when packing is enabled <a id="optional-recommended"></a> #### Optional but Recommended - Docker + Docker Compose (reproducible checks and avoids host `esbuild` platform mismatch issues) <a id="quick-start"></a> ### Quick Start (API-Only Path) This is the fastest path to a successful first run. <a id="build-and-configure"></a> #### 1. Build and Configure ```bash pnpm install pnpm build export DELPHICOURIER_CONFIG="$(pwd)/examples/config.mvp.json" export OPENAI_API_KEY="sk-your-key-here" ``` Important: `examples/config.mvp.json` references `api_key_env: "OPENAI_API_KEY"`. The variable must exist in the same process context as the MCP server. Required config checks before live calls: - `repo_root` should be an absolute path to your git repo (for example `/Users/you/projects/delphicourier`). Using `"."` may fail when your MCP host launches DelphiCourier from another working directory. - `engines.openai_responses_api.base_url` must match your API gateway: - OpenAI direct: `https://api.openai.com/v1` - LiteLLM proxy: your LiteLLM URL (for example `https://litellm.example.com/v1`) - `OPENAI_API_KEY` must match the selected gateway, configure it in `~/.codex/config.toml`: - OpenAI direct: OpenAI API key - LiteLLM proxy: valid LiteLLM proxy token `~/.codex/config.toml` Configuration Example ``` [mcp_servers.delphicourier] command = "/path/to/your/node/.nvm/versions/node/v22.16.0/bin/node" args = ["/path/to/the/repo/delphicourier/dist/src/stdio.js"] [mcp_servers.delphicourier.env] DELPHICOURIER_CONFIG = "/path/to/the/repo/delphicourier/examples/config.mvp.json" OPENAI_API_KEY = "sk-xxxx" ``` <a id="dry-run-smoke-test"></a> #### 2. Run a Dry-Run Smoke Test This validates setup without spending model tokens. ```bash pnpm build node examples/run-consult-oracle.mjs examples/consult_oracle.minimal.dry_run.json ``` Expected indicators: - `status: "ok"` - `engine_attempts[*].status: "skipped"` (because `dry_run: true`) - `token_report` present <a id="live-api-call"></a> #### 3. Run a Live API Call Create `/tmp/consult_oracle.api_only.json`: ```json { "question": "Review src/server.ts", "engine_profile": "api_only", "budget_profile": "balanced", "recipe": { "version": 1, "items": [ { "type": "file_chunk", "path": "src/server.ts", "start_line": 1, "end_line": 54, "context_rank": "high" } ] } } ``` Run: ```bash pnpm build node examples/run-consult-oracle.mjs /tmp/consult_oracle.api_only.json ``` Expected indicator: - `status: "ok"` - `engine_attempts[0].status: "success"` <a id="running-as-an-mcp-server"></a> ### Running as an MCP Server <a id="local-stdio-server"></a> #### Local Stdio Server ```bash pnpm install pnpm build pnpm mcp:stdio ``` <a id="common-gotcha-host-managed-environment"></a> #### ⚠️ Common Gotcha: Host-Managed Environment If your MCP host manages server environment explicitly, you must inject both config path and API key there. Example for Codex Desktop `~/.codex/config.toml`: ```toml [mcp_servers.delphicourier] command = "node" args = ["/absolute/path/to/delphicourier/dist/src/stdio.js"] [mcp_servers.delphicourier.env] DELPHICOURIER_CONFIG = "/absolute/path/to/delphicourier/examples/config.mvp.json" OPENAI_API_KEY = "sk-..." ``` Then restart the host app so the MCP server process picks up updated env. If DelphiCourier cannot see an env var referenced in config, it returns `CONFIG_ENV_SECRET_MISSING`. <a id="engine-profiles"></a> ### Engine Profiles Defined in `examples/config.mvp.json`: - `default`: `chatgpt_web_oracle` -> `openai_responses_api` - `api_only`: `openai_responses_api` - `chatgpt_web_oracle_only`: browser-only <a id="browser-profile-setup-notes"></a> #### Browser Profile Setup Notes Browser profiles run Oracle CLI (`npx -y @steipete/oracle`). You may need a one-time manual login bootstrap to establish session/cookies. Quick check: ```bash npx -y @steipete/oracle --help ``` Then retry with `engine_profile: "default"` or `chatgpt_web_oracle_only`. <a id="configuration-resolution"></a> ### Configuration Resolution Lookup precedence: 1. `--config` 2. `DELPHICOURIER_CONFIG` 3. `DELPHICOURIER_HOME/config.json` 4. `~/.delphicourier/config.json` 5. Built-in defaults Use `get_config_summary` to confirm active profiles/config path. <a id="development-and-operations"></a> ## Development & Operations <a id="development-and-verification"></a> ### Development and Verification <a id="project-scripts"></a> #### Project Scripts - `pnpm typecheck` - `pnpm test` - `pnpm build` - `pnpm mcp:stdio` <a id="required-quality-gates"></a> #### Required Quality Gates ```bash scripts/pre-commit-checks.sh pnpm typecheck pnpm test pnpm build pnpm build && node examples/run-consult-oracle.mjs examples/consult_oracle.minimal.dry_run.json ``` <a id="publishing-and-auto-release"></a> ### Publishing & Auto Release This repo now includes: - `.github/workflows/ci.yml`: quality gates on PRs/pushes. - `.github/workflows/release.yml`: semantic-release job on `main`. - `.releaserc.json`: release branch/tag/plugin config. <a id="what-this-pipeline-does"></a> #### What This Pipeline Does On every push to `main`, the release workflow: 1. Runs `typecheck`, `test`, `build`, and dry-run smoke checks. 2. Uses semantic-release to inspect Conventional Commits. 3. Publishes to npm and creates a GitHub Release when a releasable commit is found. 4. Tags releases as `vX.Y.Z`. If there is no releasable commit, the workflow exits without publishing. <a id="one-time-setup"></a> #### One-Time Setup 1. Ensure `package.json` has the final public package name. 2. Create an npm automation token (publish permission for that package/scope). 3. Add GitHub repository secret: - `NPM_TOKEN`: npm automation token. 4. Ensure GitHub Actions has permission to create releases (enabled by default with the workflow permissions in `release.yml`). Optional but recommended: - Enable branch protection on `main` so CI must pass before merge. - Enforce Conventional Commit format (`feat:`, `fix:`, `perf:`, etc.) so version bumps are predictable. <a id="how-a-release-is-triggered"></a> #### How A Release Is Triggered - `feat:` -> minor version bump - `fix:` / `perf:` -> patch bump - `BREAKING CHANGE:` footer or `!` marker -> major bump Example: ```text feat(mcp): add context request hints for consult_oracle ``` <a id="run-with-npx-no-install"></a> #### Run with npx (No Install) After publish, users can run the MCP server without global install: ```bash npx -y delphicourier ``` For MCP hosts (example): ```toml [mcp_servers.delphicourier] command = "npx" args = ["-y", "delphicourier"] [mcp_servers.delphicourier.env] DELPHICOURIER_CONFIG = "/absolute/path/to/config.json" OPENAI_API_KEY = "sk-..." ``` <a id="dependency-model"></a> #### Dependency Model - npm package dependencies (`package.json -> dependencies`) are installed automatically when users run `npx -y delphicourier`. - Build-only tools (`devDependencies`) are used in CI/release, not at runtime. - External executables invoked by selected engine profiles are still runtime prerequisites: - `npx -y @steipete/oracle` for browser Oracle engine profiles. - `OPENAI_API_KEY` for API engine profiles. <a id="docker-workflow"></a> ### Docker Workflow (Recommended) If host tests fail due platform-native `esbuild` mismatch, use Docker for reliable verification: ```bash docker compose build docker compose run --rm dev pnpm typecheck docker compose run --rm dev pnpm test docker compose run --rm dev pnpm build docker compose run --rm dev bash -lc 'pnpm build && node examples/run-consult-oracle.mjs examples/consult_oracle.minimal.dry_run.json' ``` <a id="troubleshooting"></a> ### Troubleshooting | Error | Common Cause | Fix | | --- | --- | --- | | `CONFIG_ENV_SECRET_MISSING` | MCP server process cannot see required env var (for example `OPENAI_API_KEY`). | Confirm `api_key_env` name in config and inject/export env in the host process that launches MCP server. Restart host/server. | | `ENGINE_API_AUTH_FAILED` | Invalid key/token for configured `base_url` (for example LiteLLM proxy token mismatch). | Verify `engines.openai_responses_api.base_url`, refresh the credential in `OPENAI_API_KEY`, then restart host/server. | | `timed out awaiting tools/call` | Host timeout shorter than browser engine runtime. | Use `engine_profile: "api_only"` for setup validation or increase host tool timeout. | | `invalid_json_schema` | Running stale build or stale server process after schema changes. | `pnpm build`, then restart MCP server/host. | | `fatal: not a git repository` | Running outside repo root or wrong `repo_root` in config. | Run from repo root and/or fix `repo_root` in config. | Additional note: - `started_at` / `ended_at` values of `1970-01-01T00:00:00.000Z` in DelphiCourier outputs are expected for deterministic testability, not wall-clock time. <a id="reference"></a> ## Reference <a id="project-layout"></a> ### Project Layout - `src/`: tools, engines, schemas, config loader, prompt/shrink logic - `tests/`: unit + integration tests - `examples/`: starter config + payload samples - `scripts/`: repo checks - `tech_spec.md`: architecture, contracts, and implementation plan <a id="acknowledgments"></a> ### Acknowledgments DelphiCourier stands on the shoulders of some excellent projects: - **[Oracle](https://github.com/steipete/oracle)** (`steipete/oracle`): The core engine automation dependency and inspiration for the project's namesake. It flawlessly bridges the gap to browser-based AI runs. - **[gitcontext](https://github.com/kccarlos/gitcontext)** (`kccarlos/gitcontext`): A UI-driven predecessor for building codebase context precisely like this. It proved that granular, visual context assembly yields better AI results. - **[repomix](https://github.com/yamadashy/repomix)** (`yamadashy/repomix`): An inspiration for codebase packing and compression techniques that inform DelphiCourier's deterministic shrinking logic.