From d00001fea93afe664782ab7e4563e8d45b22ce2b Mon Sep 17 00:00:00 2001 From: gauravs19 Date: Sun, 7 Jun 2026 00:32:02 +0530 Subject: [PATCH] feat: MCP server, README overhaul, CHANGELOG v4.1.0, stashed rule updates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit mcp_server.py (new): - FastMCP server exposing all 37 rules, 17 templates, 5 personas as resources (archpilot://rules/{name}, archpilot://templates/{name}, archpilot://personas/{name}, archpilot://diagrams/{name}) - Tools: list_rules(), get_rule(), list_templates(), list_personas(), run_lint(directory, tier) → JSON, calculate_nfrs(...) → physics output - Fuzzy rule lookup: accepts bare filename, numeric prefix, or full name - Drop-in Claude Code config: add one JSON block to ~/.claude/settings.json - requirements.txt + pyproject.toml: added mcp>=1.0.0 README.md: - Install section: pip install -e . shown as primary path - Quick Start: updated to `archpilot` CLI commands with all new flags (--from-phase, --max-tokens, --format json, --model) - What is Archpilot table: added MCP Server row - Standards Library: Options D→Kiro, E→ChatGPT, F→Gemini, G→Windsurf, H→Aider, I→MCP Server (was missing Kiro from options; Options D/E generic) - New Personas section: table of all 5 personas with descriptions - File tree: added mcp_server.py, pyproject.toml, 3 new LLM configs, expanded persona descriptions - Total count: 37 rules | 17 templates | 8 LLM configs | 5 personas | MCP server CHANGELOG.md: - Added v4.1.0 entry documenting all changes from both PRs plus this PR - Moved MCP Server out of Unreleased Planned (now shipped) Stashed local improvements (committed): - rules/00-architecture-principles.md: 7 additions - rules/27-spec-driven-development.md: 29 additions - tools/nfr_calculator.py: refactor - docs/index.html: footer tweak --- CHANGELOG.md | 37 +++- README.md | 129 ++++++++++--- docs/index.html | 2 +- mcp_server.py | 279 ++++++++++++++++++++++++++++ pyproject.toml | 2 +- requirements.txt | 1 + rules/00-architecture-principles.md | 7 + rules/27-spec-driven-development.md | 29 +++ tools/nfr_calculator.py | 14 +- 9 files changed, 465 insertions(+), 35 deletions(-) create mode 100644 mcp_server.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 9e9636e..caaafd3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,14 +8,47 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## [Unreleased] — Phase 7 (Planned) ### Planned -- `archpilot-reviewer` GitHub Action for automated PR auditing - Drift Detection script comparing implementation vs `design.md` -- MCP Server packaging all rules for direct LLM integration - Fitness Function runner (ArchUnit/Spectral CI gating) - ADR DAG Visualizer for living decision graph --- +## [4.1.0] — 2026-06-07 — Pipeline Hardening, MCP Server, 3 New LLM Configs + +### Added +- **MCP Server (`mcp_server.py`):** Exposes all 37 rules, 17 templates, and 5 personas as MCP resources (`archpilot://rules/{name}`, `archpilot://templates/{name}`, `archpilot://personas/{name}`). Tools: `list_rules()`, `get_rule()`, `list_templates()`, `list_personas()`, `run_lint()`, `calculate_nfrs()`. Add to Claude Code or Claude.ai with a single JSON config entry. +- **`pyproject.toml`:** `pip install -e .` now works; exposes `archpilot` as a proper CLI entry point — no more `cd` to repo root. +- **`llm-configs/gemini-instructions.md`:** System instructions for Google AI Studio, Vertex AI, and Gemini in Google Workspace. +- **`llm-configs/windsurf-rules.md`:** `.windsurfrules` for Windsurf (Codeium) IDE including Cascade-specific workflow guidance. +- **`llm-configs/aider-conventions.md`:** Recommended `.aider.conf.yml`, Python/TS conventions, and step-by-step Archpilot workflow for Aider terminal AI. +- **`.github/workflows/archpilot-lint.yml`:** Real GitHub Actions CI workflow that runs `archpilot lint --tier 2` on PRs touching `.specs/` or `rules/` (replaces the broken `workflows/archpilot-review.yml`). +- **`.gitignore`:** Covers `.specs/` (generated client docs), Python cache, venv, OS artefacts. + +### Changed +- **Pipeline — Parallel LLD generation:** Phase 3 now uses `ThreadPoolExecutor` (max 4 workers). LLDs are independent — 3-5 services now generate concurrently, ~4× faster wall-clock. +- **Pipeline — Retry logic:** Exponential backoff on `RateLimitError` and HTTP 5xx errors (3 attempts). Pipeline no longer crashes on transient API issues. +- **Pipeline — Context budget doubled:** `cap()` limits raised across all phases (discovery 4k→8k, requirements 6k→12k, HLD 4k→8k, review artifacts 3k→6k). Claude sees significantly more of each artifact. +- **Pipeline — `max_tokens` default 8000→16000:** All phases produce materially more complete documents. +- **CLI — `--from-phase N`:** Resume `archpilot run` from any phase (0–4). Reads existing `.specs/` artifacts for earlier phases — saves re-burning tokens when iterating. +- **CLI — `--max-tokens`:** Override output token limit per Claude call from the command line. +- **CLI — `--format json` on `lint`:** Machine-readable `{"errors": [...], "warnings": [...]}` output for CI tooling. +- **CLI — `--version`:** `archpilot --version` now prints `archpilot 4.1.0`. +- **Lint tier fix:** Weak-word violations (`fast`, `scalable`, etc.) are `[WARN]` at Tier 1, `[ERROR]` at Tier 2+ (was always ERROR regardless of tier). +- **Lint false-positive fix:** Fenced code blocks are stripped before weak-word scanning — no more false positives on `fast` inside a Dockerfile or code example. +- **`init` message:** Uses `sys.argv[0]` instead of hardcoded `"python archpilot.py"`. +- **`requirements.txt`:** Added `mcp>=1.0.0`. + +### Fixed +- **`tools/generate_diagrams.py`:** Hardcoded absolute Windows path (`d:\_elfor\...`) replaced with `Path(__file__)`-relative path — any contributor can now run this tool without editing source. +- **`rules/29-agentic-ai-governance.md`:** Repaired UTF-8 mojibake on related-standards table (rendered as broken boxes on GitHub). + +### Removed +- **`workflows/archpilot-review.yml`:** Deleted — was in wrong directory (never ran), referenced non-existent published Action, used wrong API key. Superseded by `.github/workflows/archpilot-lint.yml`. +- **`dashboard/`:** Removed abandoned `dashboard/index.html` + `dashboard/style.css`. Production site is `docs/index.html`. + +--- + ## [6.1.0] — 2026-05-15 — Enterprise Hardening ### Changed - **Rule 00 (Architecture Principles):** Expanded to 25 KB+ with engineering physics, CI fitness functions, GreenOps, and chaos engineering standards diff --git a/README.md b/README.md index eec460e..4273324 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,8 @@ Archpilot is two things in one repository: | Mode | What it does | When to use | |------|-------------|-------------| | **Agentic Pipeline** | `archpilot run` — takes one requirement, runs 5 AI agent phases, produces 6 production-grade artifacts automatically | Greenfield projects, new services, ARB submissions | -| **Standards Library** | 36 rule files + 17 templates you load into Claude, Cursor, Kiro, or Copilot | Code reviews, ad-hoc design, enforcing standards in an existing project | +| **Standards Library** | 37 rule files + 17 templates you load into Claude, Cursor, Kiro, Copilot, Gemini, Windsurf, or Aider | Code reviews, ad-hoc design, enforcing standards in an existing project | +| **MCP Server** | `python mcp_server.py` — exposes all rules, templates, and tools via MCP protocol for Claude Code and Claude.ai | Native LLM integration without copy-pasting; ideal for team-wide enforcement | Both modes share the same rules and templates. The pipeline automates the workflow the library supports manually. @@ -126,20 +127,40 @@ graph TD ## 🚀 Quick Start +### Install + +```bash +git clone https://github.com/gauravs19/archpilot.git +cd archpilot +pip install -e . # installs the `archpilot` CLI globally +# or without installing: python archpilot.py +``` + ### Pipeline Mode (recommended) + ```bash # Initialize a new project -python archpilot.py init my-project +archpilot init my-project + +# Edit my-project/.specs/Input.md — paste your requirement +# Then run all 5 phases (requires ANTHROPIC_API_KEY) +export ANTHROPIC_API_KEY=sk-ant-... +archpilot run --dir my-project -# Paste your requirement into my-project/.specs/Input.md -# Then run all 5 phases -python archpilot.py run my-project +# Resume from a specific phase (e.g. redo HLD onward without re-running Discovery) +archpilot run --dir my-project --from-phase 2 -# Validate all artifacts (tier 3 = strictest) -python archpilot.py lint --tier 3 --dir my-project +# Use a larger model with more output tokens for richer documents +archpilot run --dir my-project --model claude-opus-4-8 --max-tokens 32000 -# Review a specific artifact -python archpilot.py review --file my-project/.specs/Design_HLD.md +# Validate all artifacts (tier 2=standard, tier 3=enterprise strictest) +archpilot lint --dir my-project --tier 2 + +# Machine-readable lint output for CI tooling +archpilot lint --dir my-project --tier 2 --format json + +# Re-run only the guardrail audit after manual edits +archpilot review --dir my-project ``` **📖 [Full User Guide →](docs/user-guide.md)** | **📂 [DroneOps Example →](examples/droneops-fleet-management/)** @@ -164,14 +185,69 @@ python archpilot.py review --file my-project/.specs/Design_HLD.md 1. Copy [`llm-configs/cursor-rules.md`](./llm-configs/cursor-rules.md) to your project as `.cursorrules` 2. Cursor follows your architecture standards automatically -### Option D: ChatGPT Custom GPT +### Option D: AWS Kiro +1. Copy [`llm-configs/kiro-steering-instructions.md`](./llm-configs/kiro-steering-instructions.md) to `.kiro/steering/archpilot-standards.md` +2. Kiro applies these standards automatically in every agent session + +### Option E: ChatGPT Custom GPT 1. Create a new Custom GPT -2. Paste [`llm-configs/claude-project-instructions.md`](./llm-configs/claude-project-instructions.md) as system instructions (works for ChatGPT too) +2. Paste [`llm-configs/chatgpt-custom-gpt.md`](./llm-configs/chatgpt-custom-gpt.md) as system instructions 3. Upload rule files as knowledge -### Option E: Any LLM (Gemini, Groq, etc.) -1. Copy the relevant rule file content -2. Prefix your prompt: *"Follow these standards: [paste rules]. Now create..."* +### Option F: Google Gemini +1. Open [Google AI Studio](https://aistudio.google.com) → New Project +2. Paste [`llm-configs/gemini-instructions.md`](./llm-configs/gemini-instructions.md) as System Instructions +3. For Vertex AI, pass it as the `system_instruction` field in your API call + +### Option G: Windsurf IDE +1. Copy [`llm-configs/windsurf-rules.md`](./llm-configs/windsurf-rules.md) to your project root as `.windsurfrules` +2. Windsurf's Cascade agent follows your architecture standards automatically + +### Option H: Aider (terminal AI) +1. Copy [`llm-configs/aider-conventions.md`](./llm-configs/aider-conventions.md) to your project +2. Reference it in `.aider.conf.yml` with `read: [llm-configs/aider-conventions.md]` +3. See the file for recommended session commands + +### Option I: MCP Server (Claude Code / Claude.ai) + +Run Archpilot as a local MCP server so any Claude session can read rules on demand — no copy-pasting required. + +```bash +pip install -e . # install the mcp dependency +python mcp_server.py # starts the MCP server on stdio +``` + +**Add to Claude Code** (`~/.claude/settings.json`): +```json +{ + "mcpServers": { + "archpilot": { + "command": "python", + "args": ["/absolute/path/to/archpilot/mcp_server.py"] + } + } +} +``` + +Once connected, Claude can call: +- `list_rules()` — discover all 37 rules +- `get_rule("03-hld-standards")` — fetch a specific rule +- `run_lint("./my-project")` — lint specs and get JSON results +- `calculate_nfrs(tps=5000, payload_kb=2, retention_days=90)` — NFR physics + +--- + +## 🎭 Personas + +Switch the LLM's expertise and tone with a drop-in persona. Paste into any system prompt: + +| Persona | Best for | +|---------|----------| +| [`enterprise-architect.md`](./llm-configs/personas/enterprise-architect.md) | Full system design, ARB submissions, greenfield architecture | +| [`security-architect.md`](./llm-configs/personas/security-architect.md) | Threat modelling, compliance, zero-trust design reviews | +| [`presales-solutioner.md`](./llm-configs/personas/presales-solutioner.md) | RFP responses, estimation, solution narrative for clients | +| [`startup-cto.md`](./llm-configs/personas/startup-cto.md) | MVP-first design, pragmatic trade-offs, speed-to-market | +| [`vibe-code-reviewer.md`](./llm-configs/personas/vibe-code-reviewer.md) | Production readiness review of AI-generated code | --- @@ -180,8 +256,10 @@ python archpilot.py review --file my-project/.specs/Design_HLD.md ``` archpilot/ ├── archpilot.py # 🚀 CLI entry point (init, run, review, lint) +├── mcp_server.py # 🔌 MCP server — rules, templates, tools over MCP protocol +├── pyproject.toml # 📦 pip install -e . → exposes `archpilot` CLI entry point ├── tools/ # 🛠️ Executable Tools -│ ├── pipeline.py # 5-phase agentic engine (Anthropic SDK) +│ ├── pipeline.py # 5-phase agentic engine (Anthropic SDK, parallel LLDs) │ ├── nfr_calculator.py # Enterprise NFR physics (Little's Law, IOPS, egress) │ └── generate_diagrams.py # Generator for standard Mermaid archetypes ├── rules/ # 🧠 Architecture Standards & Guidelines (50 files) @@ -270,18 +348,21 @@ archpilot/ │ ├── data-contract-template.md # Producer/consumer data contract │ └── multi-agent-handoff-template.md # Handoff contract for orchestrator/sub-agents │ -├── llm-configs/ # 🤖 Platform-Specific LLM Instructions -│ ├── claude-project-instructions.md # Ready for Claude Projects +├── llm-configs/ # 🤖 Platform-Specific LLM Instructions (8 configs) +│ ├── claude-project-instructions.md # Claude Projects / Claude.ai │ ├── chatgpt-custom-gpt.md # ChatGPT Custom GPT configuration │ ├── vscode-copilot-instructions.md # GitHub Copilot (.github/copilot-instructions.md) │ ├── cursor-rules.md # Cursor IDE (.cursorrules) │ ├── kiro-steering-instructions.md # AWS Kiro steering file (.kiro/steering/) -│ └── personas/ -│ ├── enterprise-architect.md # Senior architect persona -│ ├── security-architect.md # Security architecture reviewer -│ ├── presales-solutioner.md # Presales / proposal persona -│ ├── startup-cto.md # Startup / MVP-first persona -│ └── vibe-code-reviewer.md # Production review of AI-generated code +│ ├── gemini-instructions.md # Google Gemini / Vertex AI system instructions +│ ├── windsurf-rules.md # Windsurf IDE (.windsurfrules) +│ ├── aider-conventions.md # Aider terminal AI (.aider.conf.yml + session guide) +│ └── personas/ # 🎭 Drop-in expertise personas +│ ├── enterprise-architect.md # Senior architect — full system design +│ ├── security-architect.md # Security reviewer — threat modelling, compliance +│ ├── presales-solutioner.md # Presales — RFP responses, estimation +│ ├── startup-cto.md # Startup CTO — MVP-first, pragmatic trade-offs +│ └── vibe-code-reviewer.md # Production readiness review of AI-generated code │ ├── examples/ # 📄 Sample Outputs & Reference Runs │ ├── droneops-fleet-management/ # ⭐ Full pipeline run — 94.1/100 (8 artifacts) @@ -306,7 +387,7 @@ archpilot/ └── README.md # This file ``` -**Total: 50 rules | 17 templates | 5 LLM configs | 5-phase agentic pipeline | ~500 KB of enterprise architecture standards** +**Total: 37 rules | 17 templates | 8 LLM configs | 5 personas | MCP server | 5-phase agentic pipeline | ~500 KB of enterprise architecture standards** --- diff --git a/docs/index.html b/docs/index.html index d81ebfa..2c6fdc4 100644 --- a/docs/index.html +++ b/docs/index.html @@ -948,7 +948,7 @@

Platform Configs

- © 2026 Gaurav Sharma. MIT License. Open source. + © 2026 Gaurav Sharma. MIT License. Open source. · Built with gs-theme
GitHub Portfolio diff --git a/mcp_server.py b/mcp_server.py new file mode 100644 index 0000000..0ab29fa --- /dev/null +++ b/mcp_server.py @@ -0,0 +1,279 @@ +#!/usr/bin/env python3 +""" +Archpilot MCP Server + +Exposes all Archpilot rules, templates, and personas as MCP resources, +and provides lint + NFR-calculator tools — so any MCP-compatible client +(Claude Code, Claude.ai, Cursor, etc.) can read standards on demand +without copy-pasting files. + +Usage +----- + # stdio transport (Claude Code / Claude.ai) + python mcp_server.py + + # Add to Claude Code settings: + # { + # "mcpServers": { + # "archpilot": { + # "command": "python", + # "args": ["/path/to/archpilot/mcp_server.py"] + # } + # } + # } + +Resources exposed +----------------- + archpilot://rules/index — table of all rules with descriptions + archpilot://rules/{name} — full content of a named rule file + archpilot://templates/index — table of all templates + archpilot://templates/{name} — full content of a named template + archpilot://personas/{name} — full content of a persona file + archpilot://diagrams/{name} — Mermaid archetype diagram + +Tools exposed +------------- + list_rules() — structured index of all rules + get_rule(name) — fetch a single rule by filename or number + list_templates() — index of all templates + run_lint(directory, tier) — run archpilot lint and return JSON results + calculate_nfrs(tps, payload_kb, retention_days, latency_ms, sla, rw_ratio) + — run the NFR physics calculator +""" + +import sys +import json +import subprocess +from pathlib import Path + +try: + from mcp.server.fastmcp import FastMCP +except ImportError: + print( + "mcp SDK not installed. Run: pip install mcp\n" + "Or: pip install -r requirements.txt", + file=sys.stderr, + ) + sys.exit(1) + +# ─── Paths ──────────────────────────────────────────────────────────────────── +ROOT = Path(__file__).parent +RULES_DIR = ROOT / "rules" +TMPL_DIR = ROOT / "templates" +PERSONA_DIR = ROOT / "llm-configs" / "personas" +DIAG_DIR = ROOT / "diagrams" + +# ─── Server ─────────────────────────────────────────────────────────────────── +mcp = FastMCP( + "Archpilot Standards Library", + instructions=( + "You have access to the full Archpilot enterprise architecture standards library. " + "Use the resources to read specific rule files, templates, and personas. " + "Use list_rules() to discover available rules before fetching them. " + "When a user asks for architecture help, read the relevant rule(s) first." + ), +) + +# ─── Helpers ────────────────────────────────────────────────────────────────── + +def _read(path: Path) -> str: + if not path.exists(): + raise FileNotFoundError(f"Not found: {path.name}") + return path.read_text(encoding="utf-8") + +def _rule_description(stem: str) -> str: + """Extract the first non-empty non-heading line from a rule file as a short desc.""" + path = RULES_DIR / f"{stem}.md" + if not path.exists(): + return "" + for line in path.read_text(encoding="utf-8").splitlines(): + stripped = line.strip() + if stripped and not stripped.startswith("#") and not stripped.startswith("