clade-mcp 0.1.0__tar.gz

clade_mcp-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+logs/
+orchestrator/.venv/
+orchestrator/Caddyfile
+orchestrator/caddy.log
+**/__pycache__/
+*.pyc
+*.pyo
+.claude/
+orchestrator/.claude/

clade_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: clade-mcp
+Version: 0.1.0
+Summary: MCP server exposing 29 AI coding skills — autonomous commits, loops, reviews, incident response, and more
+Project-URL: Homepage, https://github.com/shenxingy/clade
+Project-URL: Repository, https://github.com/shenxingy/clade
+Project-URL: Issues, https://github.com/shenxingy/clade/issues
+Author-email: Xingy Shen <shenxingy@users.noreply.github.com>
+License-Expression: MIT
+Keywords: ai,automation,claude,claude-code,coding,mcp,skills
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# clade-mcp
+
+MCP server that exposes **29 AI coding skills** as callable tools — autonomous commits, goal-driven loops, code reviews, incident response, security audits, and more.
+
+Part of the [Clade](https://github.com/shenxingy/clade) autonomous coding framework.
+
+## Quick Start
+
+### With Claude Desktop / Claude Code
+
+Add to your MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "clade": {
+      "command": "uvx",
+      "args": ["clade-mcp"]
+    }
+  }
+}
+```
+
+### With Cursor / Windsurf / other MCP clients
+
+```json
+{
+  "mcpServers": {
+    "clade": {
+      "command": "clade-mcp"
+    }
+  }
+}
+```
+
+### Install manually
+
+```bash
+pip install clade-mcp
+clade-mcp  # starts the MCP server (stdio transport)
+```
+
+## Prerequisites
+
+- **Python 3.10+**
+- **Claude Code CLI** installed and in PATH ([install guide](https://docs.anthropic.com/en/docs/claude-code))
+  - Skills execute via `claude -p`, so the CLI must be available
+
+## Available Skills (29)
+
+| Skill | Description |
+|-------|-------------|
+| **commit** | Analyze changes, split into logical commits by module, push |
+| **loop** | Goal-driven autonomous improvement loop (Blueprint architecture) |
+| **review** | Coverage-driven review — test all VERIFY.md checkpoints |
+| **review-pr** | AI-powered PR code review with structured feedback |
+| **investigate** | Root cause analysis — no fix without confirmed hypothesis |
+| **incident** | Incident response — diagnose, postmortem, follow-up tasks |
+| **cso** | Security audit (OWASP + STRIDE) |
+| **map** | Generate ARCHITECTURE.md with Mermaid diagrams |
+| **research** | Deep research on a topic with web search |
+| **batch-tasks** | Execute TODO steps via unattended sessions |
+| **handoff** | Save session state for context relay between agents |
+| **pickup** | Resume from a previous handoff |
+| **start** | Autonomous session launcher |
+| **verify** | Verify project behavior anchors (compile, test, lint) |
+| **sync** | End-of-session doc sync (TODO.md, PROGRESS.md) |
+| **document-release** | Post-ship documentation sync |
+| **brief** | Morning briefing — overnight activity, costs, next steps |
+| **retro** | Engineering retrospective from git history |
+| **next** | Multi-angle "what's next?" priority session |
+| **orchestrate** | Decompose goals into tasks for worker execution |
+| **frontend-design** | Create production-grade frontend interfaces |
+| **audit** | Audit correction rules for promotion/cleanup |
+| **merge-pr** | Squash-merge PR and clean up branch |
+| **worktree** | Create git worktrees for parallel sessions |
+| **pipeline** | Check health of background pipelines |
+| **provider** | Switch LLM provider |
+| **slt** | Toggle statusline display mode |
+| **model-research** | Research latest Claude models |
+| **minimax-usage** | Check API usage quota |
+
+## How It Works
+
+1. On startup, the server loads all bundled skill definitions
+2. Each skill is registered as an MCP tool with auto-generated JSON Schema
+3. When a tool is called, the skill prompt is executed via `claude -p` in your project directory
+4. Results are returned through the MCP protocol
+
+Skills from `~/.claude/skills/` (installed via Clade's `install.sh`) are also loaded and merged.
+
+## Full Clade Framework
+
+This MCP server is one part of Clade. The full framework includes:
+
+- **22 hooks** — safety guardian, correction learning, type-checking, session context
+- **30 scripts** — committer, loop-runner, parallel task execution, health scanning
+- **5 agents** — code-reviewer, test-runner, type-checker, paper-reviewer, verify-app
+- **Orchestrator** — FastAPI web UI with task queue, worker pool, GitHub sync
+
+Install the full framework:
+
+```bash
+git clone https://github.com/shenxingy/clade.git
+cd clade && ./install.sh
+```
+
+## License
+
+MIT

clade_mcp-0.1.0/README.md

@@ -0,0 +1,110 @@
+# clade-mcp
+
+MCP server that exposes **29 AI coding skills** as callable tools — autonomous commits, goal-driven loops, code reviews, incident response, security audits, and more.
+
+Part of the [Clade](https://github.com/shenxingy/clade) autonomous coding framework.
+
+## Quick Start
+
+### With Claude Desktop / Claude Code
+
+Add to your MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "clade": {
+      "command": "uvx",
+      "args": ["clade-mcp"]
+    }
+  }
+}
+```
+
+### With Cursor / Windsurf / other MCP clients
+
+```json
+{
+  "mcpServers": {
+    "clade": {
+      "command": "clade-mcp"
+    }
+  }
+}
+```
+
+### Install manually
+
+```bash
+pip install clade-mcp
+clade-mcp  # starts the MCP server (stdio transport)
+```
+
+## Prerequisites
+
+- **Python 3.10+**
+- **Claude Code CLI** installed and in PATH ([install guide](https://docs.anthropic.com/en/docs/claude-code))
+  - Skills execute via `claude -p`, so the CLI must be available
+
+## Available Skills (29)
+
+| Skill | Description |
+|-------|-------------|
+| **commit** | Analyze changes, split into logical commits by module, push |
+| **loop** | Goal-driven autonomous improvement loop (Blueprint architecture) |
+| **review** | Coverage-driven review — test all VERIFY.md checkpoints |
+| **review-pr** | AI-powered PR code review with structured feedback |
+| **investigate** | Root cause analysis — no fix without confirmed hypothesis |
+| **incident** | Incident response — diagnose, postmortem, follow-up tasks |
+| **cso** | Security audit (OWASP + STRIDE) |
+| **map** | Generate ARCHITECTURE.md with Mermaid diagrams |
+| **research** | Deep research on a topic with web search |
+| **batch-tasks** | Execute TODO steps via unattended sessions |
+| **handoff** | Save session state for context relay between agents |
+| **pickup** | Resume from a previous handoff |
+| **start** | Autonomous session launcher |
+| **verify** | Verify project behavior anchors (compile, test, lint) |
+| **sync** | End-of-session doc sync (TODO.md, PROGRESS.md) |
+| **document-release** | Post-ship documentation sync |
+| **brief** | Morning briefing — overnight activity, costs, next steps |
+| **retro** | Engineering retrospective from git history |
+| **next** | Multi-angle "what's next?" priority session |
+| **orchestrate** | Decompose goals into tasks for worker execution |
+| **frontend-design** | Create production-grade frontend interfaces |
+| **audit** | Audit correction rules for promotion/cleanup |
+| **merge-pr** | Squash-merge PR and clean up branch |
+| **worktree** | Create git worktrees for parallel sessions |
+| **pipeline** | Check health of background pipelines |
+| **provider** | Switch LLM provider |
+| **slt** | Toggle statusline display mode |
+| **model-research** | Research latest Claude models |
+| **minimax-usage** | Check API usage quota |
+
+## How It Works
+
+1. On startup, the server loads all bundled skill definitions
+2. Each skill is registered as an MCP tool with auto-generated JSON Schema
+3. When a tool is called, the skill prompt is executed via `claude -p` in your project directory
+4. Results are returned through the MCP protocol
+
+Skills from `~/.claude/skills/` (installed via Clade's `install.sh`) are also loaded and merged.
+
+## Full Clade Framework
+
+This MCP server is one part of Clade. The full framework includes:
+
+- **22 hooks** — safety guardian, correction learning, type-checking, session context
+- **30 scripts** — committer, loop-runner, parallel task execution, health scanning
+- **5 agents** — code-reviewer, test-runner, type-checker, paper-reviewer, verify-app
+- **Orchestrator** — FastAPI web UI with task queue, worker pool, GitHub sync
+
+Install the full framework:
+
+```bash
+git clone https://github.com/shenxingy/clade.git
+cd clade && ./install.sh
+```
+
+## License
+
+MIT

clade_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "clade-mcp"
+version = "0.1.0"
+description = "MCP server exposing 29 AI coding skills — autonomous commits, loops, reviews, incident response, and more"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Xingy Shen", email = "shenxingy@users.noreply.github.com" },
+]
+keywords = ["mcp", "claude", "ai", "coding", "skills", "automation", "claude-code"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "mcp>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/shenxingy/clade"
+Repository = "https://github.com/shenxingy/clade"
+Issues = "https://github.com/shenxingy/clade/issues"
+
+[project.scripts]
+clade-mcp = "clade_mcp:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/clade_mcp"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"skills" = "clade_mcp/skills"

clade_mcp-0.1.0/server.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.shenxingy/clade",
+  "description": "29 AI coding skills as MCP tools — autonomous commits, goal-driven loops, code reviews, incident response, security audits, architecture mapping, and more. Part of the Clade autonomous coding framework.",
+  "repository": {
+    "url": "https://github.com/shenxingy/clade",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "clade-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "runtime": "python",
+      "runtimeArgs": ["-m", "clade_mcp"]
+    }
+  ]
+}

clade_mcp-0.1.0/skills/audit/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: audit
+description: Audit corrections/rules.md — find rules that should be promoted to CLAUDE.md/hooks, redundant rules, or contradictions. Run periodically to keep the learning system clean.
+when_to_use: "audit corrections, review rules, promote rules, correction rules"
+user_invocable: true
+---

clade_mcp-0.1.0/skills/audit/prompt.md

@@ -0,0 +1,129 @@
+You are the Audit skill. You review the corrections/rules.md learning system, show improvement trends, and auto-promote mature rules.
+
+## Scope Detection
+
+First, determine the audit scope:
+
+- **Project mode** (default): If `.claude/corrections/rules.md` exists in the current project directory, use it. Promote mature rules to the project's `CLAUDE.md`.
+- **Global mode**: If the user passed `global` as an argument, OR if no project-local rules.md exists, use `~/.claude/corrections/rules.md` and promote to `~/.claude/CLAUDE.md`.
+
+All path references below use `RULES_FILE` and `CLAUDE_TARGET` as placeholders for the resolved paths.
+
+## Process
+
+### Step 0: Show improvement trends
+
+Read `~/.claude/corrections/scorecards.jsonl` (if it exists). Compute weekly averages for the last 4 weeks:
+
+```
+Weekly Trend:
+  Corrections/session:  2.1 → 1.8 → 1.5 → 1.2  ↓ improving
+  Score:                0.72 → 0.75 → 0.80 → 0.83  ↑ improving
+  Sessions tracked:     12
+```
+
+If scorecards.jsonl doesn't exist or has <4 entries, show "Not enough data for trends yet." and continue.
+
+### Step 1: Read context
+
+1. Read `RULES_FILE` — the learned rules for this scope
+2. Read `CLAUDE_TARGET` — the config that rules will be promoted into
+3. Read `~/.claude/hooks/` script names and their purposes (from comments)
+
+### Step 2: Cluster similar rules
+
+Before classifying, group rules by domain. If 3+ rules share the same domain tag (e.g., `css`, `shell`, `async`), suggest a generalized principle that replaces the individual rules.
+
+```
+Cluster: "css" (3 rules)
+  Suggested generalization: "CSS overflow properties clip absolutely-positioned children.
+  Never use overflow-hidden/auto on containers with popovers, dropdowns, or portals."
+  → Replaces rules from [2026-02-25] css, [2026-02-25] overflow-portal, [2026-02-25] ui-visibility
+```
+
+### Step 3: Classify each rule
+
+For each rule in RULES_FILE:
+
+#### PROMOTE — Rule is stable and should become a permanent config
+- The rule has been in rules.md for 14+ days without being contradicted
+- It describes a general pattern (not a one-off fix)
+- If a cluster generalization exists, promote the generalization instead of individual rules
+
+#### REDUNDANT — Rule duplicates existing config
+- The rule says the same thing as something already in CLAUDE_TARGET or a hook
+
+#### CONTRADICT — Rule conflicts with existing config
+- The rule says to do X, but CLAUDE_TARGET or a hook says to do Y
+- Action: Flag for human decision
+
+#### KEEP — Rule is still relevant and not yet ready to promote
+- Recent rule (< 14 days) or context-specific
+
+### Step 4: Execute promotions
+
+For PROMOTE rules, **automatically**:
+1. Append the rule text to the appropriate section in `CLAUDE_TARGET`, tagged with `[auto-promoted YYYY-MM-DD]`
+   - CSS/UI rules → under "# Coding Standards" or "# Full Stack Specific"
+   - Shell/deploy rules → under "# Agent Ground Rules"
+   - Workflow rules → under "# Workflow Preferences"
+2. Remove the promoted rule(s) from `RULES_FILE`
+
+For REDUNDANT rules, **automatically**:
+1. Remove from `RULES_FILE`
+
+For CONTRADICT rules:
+1. Show both the rule and the conflicting config
+2. Ask the user which to keep
+
+### Step 5: Update audit timestamp
+
+Touch the `.last-audit` file in the same directory as `RULES_FILE`. For example, if `RULES_FILE` is `.claude/corrections/rules.md`, run:
+```bash
+touch .claude/corrections/.last-audit
+```
+If `RULES_FILE` is `~/.claude/corrections/rules.md`, run:
+```bash
+touch ~/.claude/corrections/.last-audit
+```
+
+### Step 6: Show summary
+
+```
+Audit Results [scope: project | global]:
+  Trends:     Score 0.72 → 0.83 over 4 weeks (↑ improving)
+
+  PROMOTE (2):
+    - [2026-02-10] shell: Cross-platform stat → Added to CLAUDE.md "Agent Ground Rules"
+    - Cluster "css" (3 rules) → Generalized and added to "Full Stack Specific"
+
+  REDUNDANT (1):
+    - [2026-02-15] git: Use committer script → Already in CLAUDE.md
+
+  CONTRADICT (0): (none)
+
+  KEEP (3):
+    - [2026-02-22] frontend: Prefer server components → Too recent
+
+  Rules: 10 → 6 (promoted 2, removed 1 redundant, 1 cluster generalized)
+  Next audit nudge: 7 days from now
+```
+
+## Rules
+
+- Always execute promotions and removals automatically — don't just suggest
+- If CLAUDE_TARGET doesn't have a matching section, append to the end under a new `## Auto-Promoted Rules` section
+- Project-mode rules.md: keep under 100 lines; global rules.md: keep under 50 lines — if over, remove oldest KEEP rules first
+- Touch .last-audit even if no changes were made
+
+
+---
+
+## Completion Status
+
+- ✅ **DONE** — task completed successfully
+- ⚠ **DONE_WITH_CONCERNS** — completed but with caveats to note
+- ❌ **BLOCKED** — cannot proceed; write details to `.claude/blockers.md`
+- ❓ **NEEDS_CONTEXT** — missing information; use AskUserQuestion
+
+**3-strike rule:** If the same approach fails 3 times, switch to BLOCKED — do not retry indefinitely.

clade_mcp-0.1.0/skills/batch-tasks/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: batch-tasks
+description: Execute TODO.md steps via unattended Claude Code sessions
+when_to_use: "run tasks, execute TODO, batch execute, 批量执行, run steps"
+argument-hint: '[step2 step4 ...] | "task1" "task2" ... | --run [file] | --dry-run [file] | --parallel [file]'
+user_invocable: true
+---
+
+# Batch Tasks Skill
+
+Read steps from TODO.md, auto-plan implementation details, and run them sequentially (or in parallel) via `claude -p`. Each task runs in a fresh Claude Code session with pre-generated plans.
+
+## Key features
+
+- **TODO.md integration** — Reads project TODO.md, parses steps and unchecked items. Default: first uncompleted step. Specify steps: `/batch-tasks step2 step4`.
+- **Auto-planning** — Before writing tasks, the skill researches relevant files in the current session (which has codebase context) and generates detailed implementation plans with file paths, line numbers, and patterns to follow. This dramatically reduces token waste from redundant exploration in `claude -p` sessions.
+- **Scout scoring** — Each task is scored (0-100) before execution. Tasks scoring <50 are skipped and a GitHub Issue is created instead. Tasks 50-79 are flagged as risky.
+- **Per-task model assignment** — Each task is automatically assigned `haiku` (simple deletions, <20 lines), `sonnet` (standard features, 2-4 files), or `opus` (architectural, 5+ files) based on complexity.
+- **Per-task timeout & retries** — Each task has a configurable timeout (default 10 min) and retry count (default 2). Timed-out or failed tasks are rolled back via git and retried automatically.
+- **Failure resilience** — Failed tasks don't kill the batch. After all retries are exhausted, failures are logged to PROGRESS.md and a GitHub Issue is created automatically.
+- **Parallel execution** — `--parallel` flag runs independent tasks concurrently using git worktrees, with automatic conflict detection and merge.
+- **Background execution** with live progress monitoring
+
+## Usage
+
+### Execute TODO steps (primary usage)
+```
+/batch-tasks              # First uncompleted step from TODO.md
+/batch-tasks step2        # Execute Step 2
+/batch-tasks step2 step4  # Execute Steps 2 and 4
+```
+
+### Run from quoted task descriptions
+```
+/batch-tasks "Fix sidebar padding" "Add loading skeleton to /projects"
+```
+
+### Run / preview an existing task file
+```
+/batch-tasks --run                # Serial execution
+/batch-tasks --parallel           # Parallel execution (git worktrees)
+/batch-tasks --dry-run
+```
+
+## How it works
+
+1. **Parse TODO.md** — Finds the target step(s), extracts unchecked `- [ ]` items
+2. **Planning phase** — For each item, searches the codebase (Glob/Grep), reads relevant files, and generates a detailed plan with exact file paths, line numbers, and implementation steps
+3. **Scout scoring** — Each task is scored on readiness (target files found, patterns clear, no blocking deps). Tasks scoring <50 are skipped.
+4. **Model assignment** — Each task gets assigned `haiku`, `sonnet`, or `opus` based on complexity
+5. Tasks are written to `tasks.txt` in delimited block format
+6. `~/.claude/scripts/run-tasks.sh` (serial) or `~/.claude/scripts/run-tasks-parallel.sh` (parallel) executes tasks
+7. Each task runs with a timeout; on failure, working tree is rolled back and the task is retried
+8. Logs go to `logs/claude-tasks/` with timestamps (per attempt)
+9. After all tasks complete: success/failure summary, failures logged to PROGRESS.md + GitHub Issue