solution-architecture-mcp-toolkit
Bilingual MCP toolkit for ADRs, threat modeling, and governed Well-Architected reviews.
git clone https://github.com/fernandofatech/solution-architecture-mcp-toolkit.gitsolution-architecture-mcp-toolkit is a Python-based CLI and template library that encodes real architecture practice — ADRs, AWS Well-Architected reviews, threat modeling, cost and risk workflows — into MCP-compatible tools so AI agents can accelerate architecture work without bypassing governance.
What this project is and why I built it
Most AI-assisted architecture workflows today amount to pasting a diagram into a chat window and asking for opinions. That approach produces text, not decisions — and it leaves no audit trail, no security review, no cost rationale, and no accountability.
This toolkit takes a different position: architecture discipline should be encoded into the tools themselves, not left to the quality of a prompt. The project wraps well-established practices — Architecture Decision Records (ADRs), the AWS Well-Architected Framework's five pillars, STRIDE-style threat modeling, and cost/risk review checklists — into a CLI (sa-toolkit) and a set of MCP-compatible tool definitions that an AI agent can call with structure and return structured output.
The repository is also a portfolio artifact. It is bilingual (English and Portuguese), documented to production standards, and deployed as a static frontend on Vercel at mcp-toolkit.moretes.com. The stack is intentionally lean: Python for the CLI and tool logic, HTML/CSS/JavaScript for the frontend, with no heavy framework dependencies that would obscure the architecture concepts being demonstrated.
If you work with solution architecture, platform engineering, or DevSecOps and want a concrete example of how to make AI tooling governance-aware rather than governance-free, this is the reference I built for that purpose.
What the toolkit covers
How the toolkit fits together
A developer or AI agent invokes the CLI, which routes to tool modules. Each module produces structured output (ADR files, checklist reports, threat model documents). The frontend on Vercel surfaces the portfolio; the Python package is installed and tested independently.
- Architect · or Developer
- AI Agent · (MCP client)
- sa-toolkit · CLI entry point
- ADR Tool · adr --title --context --decision
- Well-Architected · Checklist Tool
- Threat Model · Prompts & Templates
- Cost & Risk · Review Workflow
- ADR Markdown · File
- Checklist / · Review Report
- Threat Model · Document
- Vercel · mcp-toolkit.moretes.com
- GitFlow + · Security Pipeline
Installing and using the toolkit
- 1
Clone the repository
Start by cloning locally. The repo contains both the Python package and the frontend under
frontend/. - 2
Install the Python package and test runner
Run
python -m pip install -e . pytestfrom the repository root. The-eflag installs in editable mode so changes to tool modules are reflected immediately without reinstalling. - 3
Run the Well-Architected review
Call
sa-toolkit well-architectedto start an interactive checklist walk-through covering all five AWS Well-Architected pillars. Output is structured and suitable for committing as a review artifact. - 4
Generate an ADR
Use
sa-toolkit adr --title "Use Amazon EventBridge" --context "Need decoupling" --decision "Adopt EventBridge"to scaffold a complete ADR markdown file. Supply your own title, context, and decision text. - 5
Run the test suite
Run
pytest -qto verify the tool modules. Keep this green before committing; the security pipeline in OPERATIONS.md runs the same suite on push. - 6
Build and deploy the frontend (optional)
Change into the
frontend/directory, runnpm cito install dependencies,npm run lintto check code quality, andnpm run buildto produce the static bundle. Deploy to Vercel by following the secrets and GitFlow instructions in OPERATIONS.md.
# 1. Clone
git clone https://github.com/fernandofatech/solution-architecture-mcp-toolkit.git
cd solution-architecture-mcp-toolkit
# 2. Install Python package (editable) + pytest
python -m pip install -e . pytest
# 3. Generate an Architecture Decision Record
sa-toolkit adr \
--title "Use Amazon EventBridge" \
--context "Need decoupling between order service and fulfillment" \
--decision "Adopt EventBridge as the event bus"
# 4. Run the Well-Architected checklist
sa-toolkit well-architected
# 5. Verify everything passes
pytest -q
# --- Frontend (optional) ---
cd frontend
npm ci
npm run lint
npm run buildHow it works: MCP tool design and governance encoding
The core idea is that architecture governance should live in the tool, not in the prompt. Each capability in sa-toolkit is structured as an MCP-compatible tool definition: it accepts typed, named inputs; it validates them; and it produces a deterministic, structured output that can be stored, diffed, reviewed, and audited.
For ADRs, the tool enforces the minimum fields that make a decision record useful — title, context, decision, and consequences — rather than accepting freeform text. For the Well-Architected review, the tool walks through pillar-by-pillar questions and records responses in a format that maps back to AWS's own framework documentation. For threat modeling, the templates guide the analyst through threat categories systematically rather than relying on the AI to recall them unprompted.
This design means an AI agent calling these tools via MCP gets the same structured output a human would get from the CLI. The agent cannot skip the ADR fields, cannot produce a Well-Architected review that omits a pillar, and cannot generate a threat model that lacks the structural prompts. Governance is enforced at the tool boundary, not at the conversation level.
The Python package is installed with pip install -e ., which registers the sa-toolkit entry point. The frontend is a separate, dependency-light static site under frontend/ that serves as the portfolio surface. The two concerns are deliberately decoupled: the CLI and tool logic have no dependency on the frontend, and the frontend has no runtime dependency on the Python package.
Why MCP over plain prompts
MCP (Model Context Protocol) lets you define tools with typed schemas that an AI agent calls explicitly, rather than inferring intent from freeform text. For architecture work this matters: a tool that requires --title, --context, and --decision cannot produce an ADR without those fields. A prompt can. The toolkit uses MCP conventions precisely because architecture artifacts need to be complete and consistent, not just plausible.
Common questions
Do I need an AI agent to use this? Can I use the CLI standalone?
No AI agent required. The CLI works fully standalone — sa-toolkit adr and sa-toolkit well-architected are useful on their own for any architect who wants structured, committable outputs. The MCP-compatible design is there if you want to wire the tools into an agent workflow, but it is not a prerequisite.
Is this tied to AWS specifically?
The Well-Architected checklist is AWS-specific — it maps to the five pillars of the AWS Well-Architected Framework. The ADR tool, threat modeling templates, and cost/risk workflows are cloud-agnostic and apply to any architecture context. The repository topics include AWS because that is my primary platform, not because the entire toolkit requires it.
What Python version is required?
The README does not specify a minimum version explicitly. Given the tooling conventions and the use of standard pip install -e . packaging, Python 3.9+ is a safe assumption. Check pyproject.toml or setup.py in the repository for the declared constraint.
How do I deploy the frontend to Vercel?
Build locally with npm ci && npm run build inside frontend/. For Vercel deployment, the GitFlow branching strategy, required secrets, and the security pipeline are documented in OPERATIONS.md in the repository root. The site is already live at mcp-toolkit.moretes.com as a reference.
Who this is for and when to use it
This toolkit is for solution architects, platform engineers, and senior engineers who want to use AI tooling without sacrificing the documentation discipline and governance that make architecture decisions traceable and defensible. If your current AI-assisted architecture workflow produces chat transcripts instead of ADRs, skips Well-Architected reviews, or treats threat modeling as optional, this repository gives you a concrete alternative. It is also a portfolio reference for anyone evaluating how to design MCP-compatible tools that encode domain knowledge rather than delegating it entirely to model inference. The bilingual documentation (English and Portuguese) and the production Vercel deployment make it a complete, inspectable example rather than a sketch. It is not the right fit if you need a fully hosted SaaS, a GUI-first experience, or deep integration with a specific AI platform out of the box. It is a toolkit — opinionated, structured, and deliberately minimal — that you extend and integrate into your own workflow.