Phases Agents MCP server

<!-- mcp-name: io.github.Cherridsaid/phases-agents -->

phases-agents

English · Français

A local MCP server that discovers, validates and selects skills deterministically. Python standard library only, no runtime dependencies.

One server. Five tools. Nothing executed behind your back.

Why

AI agents improvise. Ask the same question twice and you get two different plans. That is fine for brainstorming, and unacceptable for audit and compliance work.

phases-agents removes the improvisation. It profiles a local project, validates a catalogue of skills against a strict contract, and returns a plan that can be replayed. Same target, same catalogue, same parameters, same decision.

Principle

configured root identifiers
→ bounded discovery
→ official validation
→ immutable registry
→ verified cache
→ detector profile
→ deterministic selection
→ MCP plan

The server selects and exposes. The calling model reads the selected skills and decides what to do with them, using its own tools. The server never executes a skill.

Architecture

The modules live in src/phases_agents/.

The normative contract lives in src/phasesagents/core/SKILLSCONTRACT.md (French).

Quick start

An example package ships in examples/skills/. Three steps produce a real plan.

git clone https://github.com/Cherridsaid/phases-agents && cd phases-agents

Create skills-roots.json pointing at the example root:

{
  "config_version": "1.0",
  "roots": [
    { "id": "demo", "path": "/absolute/path/to/phases-agents/examples/skills" }
  ]
}

pip install -e .
phases-agents --skills-config /absolute/path/to/skills-roots.json

pip install -e . installs the phases-agents command. Without installing, the same server starts with PYTHONPATH=src python -m phases_agents.server.

The server reads JSON-RPC line by line on standard input. A phasesagentsplan call against a Python project then selects hello-python:

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"phases_agents_plan",
 "arguments":{"root_ids":["demo"],"target":"/absolute/path/to/a/project",
 "today":"2026-08-27","plan_version":"B3",
 "client_capabilities":["filesystem_read","filesystem_search"]}}}

Two plan formats coexist. "B3" names the versioned format, not a server version; its official schema is src/phasesagents/core/PLANB3SCHEMA.json. Use it for new work. Without planversion, the legacy format returns a flat list of steps; it is kept so existing callers do not break, and will be deprecated before removal. client_capabilities is only accepted in B3, since declaring what the client can do only makes sense in that format.

Connecting an MCP client

Claude Code (.mcp.json at the root of your project):

{
  "mcpServers": {
    "phases-agents": {
      "command": "phases-agents",
      "args": [
        "--skills-config",
        "/absolute/path/to/skills-roots.json"
      ]
    }
  }
}

Codex uses the same command/arguments pair in its own configuration file. No token and no environment variable is required.

MCP tools

Shortened. The full README is on GitHub.