# Conductor Intelligence

A read-only Project Intelligence MCP server and Codex orchestration skill for navigating Conductor projects. It exposes architecture notes, agent inventories, feature traces, and operational documentation through 16 tools.

**This repository contains the plugin only.** The Conductor video-production pipeline, its specialist agents, generated project documentation, Pipeline Memory database, provider credentials, and media assets are separate. A small, entirely synthetic project is included so you can try the plugin and run its tests without a Conductor installation.

The server uses Node.js built-ins and has no external dependencies. It reads existing intelligence files; it does not generate inventories, run agents, access the operational database, or make provider calls.

## Quick start

Requirements: Node.js 22 or newer, Git, and a client that supports MCP over standard input/output. The examples below use the Codex CLI.

```sh
git clone https://github.com/McDuckVc/conductor-intelligence.git
cd conductor-intelligence
npm test
```

No `npm install` is required. The package is marked private to prevent accidental npm publication; the source is available under the MIT license.

### Try the synthetic project

PowerShell, from the cloned repository:

```powershell
$env:CONDUCTOR_PROJECT_ROOT = (Resolve-Path './examples/minimal-project').Path
node scripts/doctor.js
$conductorServer = (Resolve-Path './server/server.js').Path
codex mcp add conductor-intelligence --env "CONDUCTOR_PROJECT_ROOT=$env:CONDUCTOR_PROJECT_ROOT" -- node "$conductorServer"
```

macOS/Linux shell, from the cloned repository:

```sh
export CONDUCTOR_PROJECT_ROOT="$(pwd)/examples/minimal-project"
node scripts/doctor.js
codex mcp add conductor-intelligence --env "CONDUCTOR_PROJECT_ROOT=$CONDUCTOR_PROJECT_ROOT" -- node "$(pwd)/server/server.js"
```

Start a new Codex session and ask:

> Use Conductor Intelligence to show the project overview, list the agents, and trace the storyboard review feature.

`CONDUCTOR_PROJECT_ROOT` must be an explicit, existing absolute directory. An unset or relative value fails with a configuration error. To connect your own project, substitute its absolute root and run the registration command again. The MCP client stores the configured path locally; do not commit personal client configuration to this repository.

### Plugin and skill packaging

The repository includes the portable Agent Plugins layout (`plugin.json`, `mcp.json`, and `skills/`) plus compatibility files (`.codex-plugin/plugin.json` and `.mcp.json`). Plugin-aware hosts expand `${PLUGIN_ROOT}` in the launch configuration. Keep `node` on the host's `PATH` and provide `CONDUCTOR_PROJECT_ROOT` in its MCP server environment.

The direct MCP registration above installs the tools only. To use the bundled orchestration skill without a plugin marketplace, copy `skills/conductor-orchestrator` into your Codex skills directory, typically `~/.codex/skills/`, then start a new session. See [Codex skills documentation](https://developers.openai.com/codex/skills/) and [plugin packaging documentation](https://developers.openai.com/plugins/build/plugins).

This repository does not register or modify a Codex plugin marketplace. Marketplace installation and client-specific plugin discovery should be configured using your host's documented workflow.

## Required project layout

```text
your-project/
├── pipeline/
│   └── SYSTEM_MANIFEST.md
└── docs/project-intelligence/
    ├── 01-project-overview.md
    ├── 03-architecture.md
    ├── 04-runtime-and-lifecycle.md
    ├── 12-mcp-tools-and-resources.md
    ├── 18-testing-and-quality.md
    ├── 19-build-deployment-and-operations.md
    ├── 20-observability-and-failure-handling.md
    ├── 24-maintenance-guide.md
    └── inventory/
        ├── agents.json
        ├── components.json
        ├── data-models.json
        ├── dependencies.json
        ├── environment-variables.json
        ├── features.json
        ├── files.json
        ├── mcp-tools.json
        ├── prompts.json
        ├── routes.json
        ├── symbols.json
        ├── tests.json
        └── traceability.json
```

`doctor` checks the marker and required directories. Document tools report missing documents when called. Every inventory file must contain a JSON array; `validate_intelligence_indexes` reports missing or malformed indexes. The server does not infer source facts or refresh stale data.

Inventory records may contain your own fields. `get_file_summary` matches a record's `path` or `file` field exactly. Agent, symbol, and feature lookups search the JSON text of their respective records, without case sensitivity. See [the example inventories](examples/minimal-project/docs/project-intelligence/inventory) for minimal shapes.

## Tools

| Tool | Purpose | Required argument |
| --- | --- | --- |
| `doctor` | Check the configured project layout | — |
| `project_overview` | Read the project overview | — |
| `repository_tree` | Return up to 200 indexed files | — |
| `search_project_docs` | Search top-level intelligence Markdown, up to 20 results | `query` |
| `get_file_summary` | Find an exact repository-relative inventory path | `path` |
| `find_symbol` | Search symbol records, up to 50 matches | `symbol` |
| `list_agents` | Read the agent inventory | — |
| `get_agent` | Search agent records, up to 50 matches | `name` |
| `trace_feature` | Search traceability records, up to 50 matches | `feature` |
| `get_architecture` | Read architecture notes | — |
| `get_runtime_flow` | Read runtime and lifecycle notes | — |
| `list_integrations` | Read dependency records | — |
| `get_failure_forensics_overview` | Read failure-handling documentation | — |
| `get_pipeline_memory_overview` | Read MCP documentation and explain the database boundary | — |
| `get_runbook` | List the three expected runbook filenames | — |
| `validate_intelligence_indexes` | Check all 13 JSON inventories | — |

String arguments must be non-empty and at most 256 characters. Large serialized responses are returned as a truncated preview. These navigation tools surface documentation; verify source evidence before making critical changes.

## Security and data boundaries

All tools are read-only. Project and intelligence paths are checked for traversal and symlink escapes. Sensitive-looking filenames are rejected, but content is not automatically redacted: keep secrets out of Markdown and JSON inventories. Use trusted project files and treat retrieved text as data rather than instructions. See [SECURITY.md](SECURITY.md) for limitations and private reporting guidance.

## Development

```sh
npm test
```

The integration self-test launches the actual server over stdio, exercises all 16 tools, checks invalid arguments and missing indexes, verifies project files are unchanged, and tests directory symlink/junction escapes. It uses temporary synthetic fixtures under the ignored `tmp/` directory and removes them on completion. CI runs on Node.js 22 and 24 on Ubuntu and Windows.

See [CONTRIBUTING.md](CONTRIBUTING.md). Licensed under the [MIT License](LICENSE). Conductor Intelligence is an independent project and is not an official OpenAI product.