io.github.Mostov82/conducted-mcp

Official7 tools

by Mostov82 · TypeScript

Conducted MCP

Stateless advisor + validator for Conducted Development: kickoff, artifact validation, rule checks.

Validates and checks artifacts and rules for Conducted Development methodology.

Captured live from the server via tools/list.

validate_artifact

Strictly check whether a Conducted Development artifact's text satisfies the methodology's required structure. Supply the artifact's type and its full text (the server never reads files). Returns { valid, missing, warnings }: `missing` lists required sections that are absent, empty, or contain only unmodified template placeholder text (blocking); `warnings` lists sections that are present but look thin (advisory, non-blocking). `valid` is true iff `missing` is empty.

Parameters (2)

artifact_typestringrequired
Which artifact to validate.
contentstringrequired
The full markdown text of the artifact to validate.

kickoff_questions

Return the branched kickoff interview (DECISIONS.md D3/D4). Supply `project_type`: 'greenfield' asks the full set; 'brownfield' uses the agent-supplied `detected` facts (language, framework, tests, CI, existing docs) to pre-fill candidates and drop fully-inferable questions — except LOCKED_DOCS, which is always asked because it is human judgment. Returns { project_type, questions, inferred, notes }; the server reads no files.

Parameters (2)

project_typestringrequired
'greenfield' or 'brownfield'.
detectedobject
Facts the agent detected by inspecting the repo (brownfield only).

kickoff_plan

Assemble, from the bundled templates, the four `_template.md` copies (front-matter tokens replaced), `decision-log.md`, and a filled `AGENT_CONVENTIONS.md` (kickoff guide Steps 2–5). Supply `project_type`, the interview `answers`, optional `detected` (brownfield pre-fill fallback), and optional `existing` (the agent's inventory of files already present). Returns { files: [{ path, content, action }], missing, open_questions, warnings }. The plan is ready iff `missing` is empty (D5 strict); a file with any unresolved {{…}} token is reported in `missing`. Idempotent: already-present files are 'review'/'skip', never overwritten. The server returns content + paths only — it writes nothing (Model C, D2/D6).

Parameters (4)

project_typestringrequired
'greenfield' or 'brownfield'.
answersobjectrequired
Confirmed interview answers keyed by token id (e.g. PROJECT_NAME, LOCKED_DOCS).
detectedobject
Facts the agent detected by inspecting the repo (brownfield only).
existingobject
Agent inventory of files already present in the target (for idempotent re-runs).

next_procedure

Return the ordered procedure for where the agent is in the methodology loop. Supply `phase` (one of: kickoff, goal_brief, intent_doc, session_open, session_active, session_close, standup) and optional `facts` (e.g. a ticket id) to tailor the output. Returns { steps, reads_first, escalation_points, notes? } sourced from the bundled guides and conventions — the procedure half of advisor + validator. The server reads no files.

Parameters (2)

phasestringrequired
Which phase of the methodology loop the agent is in.
factsobject
Optional facts to weave into the procedure (e.g. ticket id, work dir).

standup_due

Given agent-supplied facts, decide whether a standup is due. Triggers in priority order: a deliverable gate reached → 'gate'; else a dependency intersection → 'intersection'; else more than five working days since the last standup → 'weekly'; else 'none'. Working days are an input (the working week varies by team), never computed from a calendar. Returns { due, reason, detail }.

Parameters (5)

gate_reachedboolean
dependency_intersectionboolean
working_days_since_last_standupnumber
last_standup_datestring
todaystring

evaluate_gate

Encode the goal-brief rule that no session may begin while any gate is open. Supply either a structured `gates` list ([{ id, resolved }]) or a goal-brief `content` string, in which case the GATE LIST checkboxes (- [ ] / - [x]) are parsed. Returns { all_resolved, unresolved, may_begin } where may_begin === all_resolved. The server reads no files — the content is agent-supplied.

Parameters (2)

gatesarray
Structured gate list.
contentstring
A goal-brief markdown string whose GATE LIST is parsed.

decision_log_guidance

Encode the Decision-Log 'when to use it' rules. Set whichever apply: `escalation_fired`, `gate_resolved_cross_cutting`, `affects_multiple_tickets`, `override_architectural`, `confined_to_one_session`. Returns { should_log, reason, entry_template? }; when should_log is true the Context/Trigger/Decision/Rationale/Affects skeleton is returned. A decision confined to one session does not need an entry — the session notes suffice.

Parameters (5)

escalation_firedboolean
gate_resolved_cross_cuttingboolean
affects_multiple_ticketsboolean
override_architecturalboolean
confined_to_one_sessionboolean

README.md5 KBView on GitHub

Conducted MCP

An MCP server that helps an AI agent plan and track a software project the way a disciplined team would — and it was built using the very methodology it ships.

Conducted MCP exposes Conducted Development — a lightweight, intent-driven methodology — to any MCP-capable agent (Claude Desktop, Cursor, and others). It is a stateless advisor + validator: it holds no project data and touches no files or git. The agent does all the I/O; the server supplies judgment — validate this artifact, is a standup due, what's the procedure for this phase, does this decision belong in the log.

The differentiator: this repository's own work/ folder — goal briefs, intent docs, a decision log, and cycle standups — was produced under the methodology the tool implements. It is the proof of process, not a sample.

What it does

A connecting agent gets, on demand:

A guided kickoff (kickoff prompt + kickoff_questions / kickoff_plan tools) — a branching Q&A that bootstraps a project's planning structure for greenfield or existing codebases. For existing code the agent inspects the repo and the server pre-fills answers so the human confirms rather than authors from scratch.
Strict artifact validation (validate_artifact) — submit a goal brief / intent doc / session log / standup, get back { valid, missing, warnings }.
Phase procedures (next_procedure) — the ordered steps, what to read first, and the escalation points for wherever the agent is in the loop.
Mechanical rule checks (standup_due, evaluate_gate, decision_log_guidance) — the rituals a solo practitioner most often lets slide, as stateless judgments over supplied facts.

The methodology's guides, templates, and conventions are served as read-only resources (conducted://guide/*, conducted://template/*, conducted://conventions) so an agent can learn the rules in-band.

Why it's built this way (Model C)

The server cannot enforce — an agent always has direct file access. So instead of pretending to be a gatekeeper, it is an advisor: pure functions returning judgments and procedures, no side effects, nothing to host with no data and no auth-to-data. That makes it portable, trivially testable, and cheap to run locally or remotely. The reasoning is written up in docs/DESIGN_SKETCH.md and the resolved trade-offs in DECISIONS.md.

Quick start

Published on npm as conducted-mcp — runs with zero install via npx.

Add the server to your MCP client. Claude Desktop (claude_desktop_config.json) or Cursor (.cursor/mcp.json):

json

{
  "mcpServers": {
    "conducted": {
      "command": "npx",
      "args": ["-y", "conducted-mcp"]
    }
  }
}

Then ask your agent to "run the Conducted kickoff for this project," or call any tool directly.

Or connect to the hosted endpoint (no install)

A stateless Streamable HTTP endpoint runs live on Cloudflare Workers — connect by URL, nothing to install:

json

{
  "mcpServers": {
    "conducted": {
      "url": "https://conducted-mcp.jonathanmostov.workers.dev/mcp"
    }
  }
}

Because the server is stateless and holds no data (Model C), the endpoint is safe to run unauthenticated, guarded by rate limiting.

Demo

See docs/DEMO.md for a real transcript of the kickoff flow — the front-door prompt, the branched interview, and the phase procedures — captured verbatim from the running server.

Development

bash

npm install
npm run build     # bundles the methodology text, then strict tsc
npm test          # vitest
npm run lint      # eslint + prettier
npm start         # run the stdio server

The server is TypeScript on the official @modelcontextprotocol/sdk, ESM, strict mode. See CONTRIBUTING.md for the layout and conventions.

The methodology, in the repo

work/goal-briefs/ — the goal briefs that drove this build
work/intent-docs/ — one per ticket, the per-session contracts
work/standups/ — cycle-gate standups
work/decision-log.md — the append-only record of decisions
AGENT_CONVENTIONS.md — how every session runs, model- and tool-agnostic

License

Install

claude_desktop_config.json

{
  "mcpServers": {
    "conducted-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "conducted-mcp@0.1.1"
      ]
    }
  }
}