agentic-sdlc-mcp

<p align="center">
  <img src="assets/logo.svg" alt="agentic-sdlc-mcp logo" width="120">
</p>

<h1 align="center">agentic-sdlc-mcp</h1>

<p align="center">
  <strong>Governance and evidence controls for AI coding agents working in real GitHub repositories.</strong>
</p>

<p align="center">
  Let Claude Code, Cursor, and other Model Context Protocol (MCP) clients work with repository context, review gates, security evidence, and human approval points.
</p>

<p align="center">
  <a href="README_zh.md">中文</a> ·
  <a href="https://www.npmjs.com/package/agentic-sdlc-mcp">npm</a> ·
  <a href="https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.SakuraCianna%2Fagentic-sdlc-mcp">MCP Registry</a> ·
  <a href="docs/ROADMAP.md">Roadmap</a>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/agentic-sdlc-mcp"><img src="https://img.shields.io/npm/v/agentic-sdlc-mcp.svg?style=flat-square&color=blue" alt="npm version"></a>
  <a href="https://www.npmjs.com/package/agentic-sdlc-mcp"><img src="https://img.shields.io/npm/dm/agentic-sdlc-mcp.svg?style=flat-square&color=green" alt="npm downloads"></a>
  <a href="https://github.com/SakuraCianna/agentic-sdlc-mcp/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/SakuraCianna/agentic-sdlc-mcp/ci.yml?branch=main&style=flat-square" alt="CI status"></a>
  <img src="https://img.shields.io/badge/Node.js-%3E%3D22-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 22 or newer">
  <a href="LICENSE"><img src="https://img.shields.io/npm/l/agentic-sdlc-mcp.svg?style=flat-square&color=orange" alt="MIT license"></a>
</p>

`agentic-sdlc-mcp` is a software development lifecycle (SDLC) governance layer for teams that already let AI coding agents change production repositories. It turns GitHub context, policy, checks, reviews, security alerts, and release signals into 13 workflow-level MCP tools. Twelve tools are read-only. The only GitHub write tool previews changes by default.

## What changes with this MCP

AI coding agents can create code and pull requests without understanding every repository rule. This server gives the agent bounded context and gives reviewers explicit evidence gaps instead of another free-form summary.

| Concern | Without this MCP | With `agentic-sdlc-mcp` |
|---|---|---|
| Repository context | The agent starts from the prompt and guesses project conventions | `repo_context` reads bounded metadata, scripts, policy, issues, pull requests, and agent instructions |
| High-risk work | Authentication, payment, migration, and workflow changes receive a generic plan | `prepare_work_item` adds risk reasons, defensive requirements, negative scenarios, rollback, and observability |
| Issue planning | A human reformats the plan into GitHub work items | `plan_from_context` creates structured drafts and `create_issue_set` previews the exact write |
| Pull request gates | A green continuous integration (CI) badge may be treated as sufficient evidence | `quality_gate_status` separates checks, reviews, ownership, protection, labels, and missing evidence |
| Secret risk | Scanner names or keyword matches may be accepted without provenance | PR review separates trusted scanner evidence, bounded patch heuristics, and unverified gaps |
| Release and handoff | Readiness depends on free-form status summaries | Release and handoff tools preserve blockers, policy obligations, evidence warnings, and human approval points |

This server does not write code, merge pull requests, force-push, create releases, deploy software, or replace human security review.

## How it fits into a production agent workflow

The MCP sits between an AI coding agent and GitHub evidence. Repository changes still happen through the agent's normal development environment, and high-impact decisions remain with your team.

```mermaid
flowchart LR
    Policy["Engineering policy<br>and repository rules"] --> MCP["agentic-sdlc-mcp"]
    Agent["AI coding agent<br>Claude Code · Cursor · MCP client"] --> MCP
    MCP --> GitHub["GitHub API evidence"]
    GitHub --> MCP
    MCP --> Reports["Briefs · plans · gates<br>reviews · release reports"]
    Reports --> Agent
    Reports --> Human["Human review and approval"]
    Agent -. "Code · commits · pull requests" .-> GitHub
    Human -. "Merge · release · deploy" .-> GitHub
```

## Where it helps

Use the tools as decision support at the points where an autonomous agent would otherwise guess or rely on stale prose.

| Production scenario | Recommended tools | Decision artifact |
|---|---|---|
| Onboard an agent into an unfamiliar repository | `repo_context` | Repository briefing with scripts, workflows, policy, open work, and known gaps |
| Turn a feature, bug, or security goal into reviewable work | `plan_from_context` → `create_issue_set` | Work-type-aware plan, issue drafts, and preview-first GitHub issues |
| Prepare auth, payment, migration, or infrastructure work | `prepare_work_item` | Risk-aware brief with defensive requirements, negative tests, rollback, and observability |
| Detect dynamic credential construction in a patch | `review_pr_against_standard` | Patch-local findings for concatenation, interpolation, decoding, aliases, and auth-header sinks |
| Decide whether a pull request is ready for human review | `create_pr_summary` → `quality_gate_status` → `review_pr_against_standard` | Diff summary, merge-gate evidence, findings, blockers, and next actions |
| Audit repository governance | `branch_protection_status` → `workflow_permissions_audit` | Branch/ruleset evidence and GitHub Actions least-privilege findings |
| Assess release readiness | `security_triage` → `release_readiness_check` | Security-alert summary, CI evidence, release blockers, changelog status, and rollback requirements |
| Transfer work to another agent | `agent_handoff_packet` | Bounded continuation packet that labels caller assertions and evidence warnings |
| Archive a decision snapshot | `sdlc_evidence_packet` | Versioned Issue, PR, or release evidence with provenance, freshness, completeness, and a stable content digest |

## Install from npm

You need Node.js 22 or newer. Node 22 and 24 are tested in GitHub Actions. Run the published package directly from npm:

```powershell
npx -y agentic-sdlc-mcp
```

For a global CLI installation:

```powershell
npm install -g agentic-sdlc-mcp
agentic-sdlc-mcp
```

The default transport is stdio. Most MCP clients should start the package for you instead of running it in a separate terminal.

## Let a coding agent set it up

Paste this prompt into Codex, Claude Code, or another coding agent:

```text
Use npm install -g agentic-sdlc-mcp to install and configure this MCP globally. Repository: https://github.com/SakuraCianna/agentic-sdlc-mcp
Configure GITHUB_TOKEN and optional repository defaults through the MCP client's secret or environment configuration. On a trusted single-user machine, you may instead run agentic-sdlc-mcp configure or write them to ~/.agentic-sdlc-mcp.json. Never expose the token in chat, logs, or repository files; ask me for missing non-secret details.
Then verify the connection with the read-only repo_context tool and summarize its capabilities, required GitHub permissions, and safety boundaries.
```

Review every command and configuration change before approving it. Node.js 22 or newer is required.

## Connect an MCP client

Add the server to Claude Desktop, Cursor, Windsurf, or another MCP client. Inject the GitHub token through the client's secret or environment configuration.

```json
{
  "mcpServers": {
    "agentic-sdlc": {
      "command": "npx",
      "args": ["-y", "agentic-sdlc-mcp"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here",
        "GITHUB_OWNER": "your_organization",
        "GITHUB_REPO": "your_repository"
      }
    }
  }
}
```

Some Windows MCP clients require `npx` through `cmd`:

```json
{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "agentic-sdlc-mcp"]
}
```

`GITHUB_OWNER` and `GITHUB_REPO` are optional defaults. Tool calls can provide repository coordinates explicitly. Use the [GitHub permission matrix](#github-permissions) to grant only the capabilities you enable.

<details>
<summary>Local interactive configuration</summary>

```powershell
npx -y agentic-sdlc-mcp configure
```

This compatibility path stores configuration in `~/.agentic-sdlc-mcp.json`, including the GitHub token. Use it only on a trusted, single-user workstation. For production-focused setups, prefer MCP client secret injection or process environment variables.

</details>

## Verify the connection

Start with a read-only call so you can inspect the repository boundary before granting write access:

```text
Use agentic-sdlc-mcp to run repo_context for the configured repository. Include package scripts, workflows, governance, and repository policy. Do not create issues or modify GitHub.
```

Then validate the write boundary without creating anything:

```text
Generate a feature plan and pass its issue drafts to create_issue_set with dryRun: true. Show the target repository, titles, labels, body summaries, and warnings. Do not write to GitHub.
```

See the [client-neutral smoke test](docs/ai-coding-agent-smoke-test.md) for a five-minute verification path.

## Tools

The server registers 13 workflow-level tools. MCP clients receive the full input and output schemas at runtime; this catalog explains when to use each tool and how to interpret its result.

| Tool | Use it when | Main result | Access |
|---|---|---|---|
| `repo_context` | An agent needs repository facts before planning | Bounded briefing with metadata, README/package summaries, scripts, workflows, governance, policy, issues, and PRs | Read-only |
| `plan_from_context` | A goal needs an SDLC plan and issue drafts | Work-type-aware plan, confidence, clarification signal, and three to five structured issue drafts | Read-only |
| `prepare_work_item` | An agent is about to implement a