solution-architecture-mcp-toolkit
MCP tools and templates that encode architecture discipline — ADR, threat model, Well-Architected.
git clone https://github.com/fernandofatech/app-solution-architecture-mcp-toolkit.gitListen to guide
generated on playGenerated only on first play
Powered by Amazon Polly + OmniVoice
A Python toolkit with a CLI, templates and MCP-compatible tool design so an AI agent can help produce ADRs, Well-Architected checklists and threat models without giving up traceability and human accountability.
What it is and why it exists
This repository came out of a question I've heard for years in architecture reviews: "the agent already wrote it, why do I still have to decide?" The answer is that an agent writes fast, but it doesn't sign. The one who answers for the decision in an audit, during an incident or at contract renewal is a person — and that person needs a record stating what was decided, in which context and which alternatives were rejected.
The toolkit encodes that discipline into reusable tools: Architecture Decision Records, AWS Well-Architected checklists, threat-modeling prompts and templates, cost and risk review workflows, and an MCP-compatible (Model Context Protocol) tool design for architecture assistants. The point is not to replace the architect's work with generic chat — it's to give the agent a narrow, predictable interface where every output is born in the format governance requires.
What's in the repository: an installable Python package exposing the sa-toolkit command, a pytest suite, a static HTML/CSS/JavaScript frontend published on Vercel at mcp-toolkit.moretes.com, documentation in docs/architecture.md and an OPERATIONS.md covering GitFlow, Vercel secrets and the security pipeline. The application code is Python; HTML shows up as the primary language because the frontend weighs more in bytes, not in logic.
What the toolkit covers
sa-toolkit adr --title --context --decision generates a decision record with the minimum fields an audit asks for.sa-toolkit well-architected prints the pillar checklist to review before signing off a design.npm ci, lint and build as the whole cycle.How the pieces fit
The architect (or an AI agent through an MCP tool) calls the Python CLI; the CLI applies the templates and returns versionable artifacts. The frontend is a separate surface published on Vercel.
- CLI · `sa-toolkit`
- Ferramentas MCP · contratos de tool
- Templates · ADR · WA · threat model
- pytest · suíte de testes
- ADR · markdown versionado
- Checklist · Well-Architected
- Threat model · ameaças e mitigação
- Site estático · HTML/CSS/JS
Install and use
- 1
Clone and install in editable mode
git clone https://github.com/fernandofatech/app-solution-architecture-mcp-toolkit && cd app-solution-architecture-mcp-toolkit && python -m pip install -e . pytest. The-epoints the package at the working directory — edit a template and the command reflects it immediately, no reinstall. - 2
Run the Well-Architected checklist
sa-toolkit well-architectedprints the checklist. Use it before signing off a design: answering each item now is cheaper than discovering the ignored pillar during the first incident. - 3
Generate an ADR
sa-toolkit adr --title "Use Amazon EventBridge" --context "Need decoupling" --decision "Adopt EventBridge". The three fields are the minimum: title, context and decision. Commit the result alongside the code it justifies. - 4
Confirm with the tests
pytest -q. If you changed a template, the tests are what keeps a broken output from silently reaching the agent. - 5
Frontend (optional)
cd frontend && npm ci && npm run lint && npm run build. This is the static surface published on Vercel;OPERATIONS.mddocuments secrets and GitFlow.
git clone https://github.com/fernandofatech/app-solution-architecture-mcp-toolkit
cd app-solution-architecture-mcp-toolkit
# instala o pacote em modo editável + pytest
python -m pip install -e . pytest
# checklist dos pilares Well-Architected
sa-toolkit well-architected
# um ADR com os três campos mínimos
sa-toolkit adr \
--title "Use Amazon EventBridge" \
--context "Need decoupling" \
--decision "Adopt EventBridge"
# valida templates e CLI
pytest -q
# frontend estático (Vercel)
cd frontend && npm ci && npm run lint && npm run buildHow it works under the hood
The CLI is the only door: sa-toolkit is a Python entry point installed by pip install -e .. Each subcommand — adr, well-architected — takes explicit arguments and returns text ready to go into the repository. No state, no database, no network call; what comes in through the flags is everything the tool knows.
Templates are the source of truth: ADR, checklist and threat model live as templates inside the package. The CLI fills fields, it doesn't invent sections. This matters for a practical reason: when the ADR format changes — a new compliance field, say — it changes in one place, and every agent using the tool starts producing the new format without retraining anything.
MCP design on top of the same logic: the MCP-compatible tool proposal exposes the same operations as the CLI with a defined input/output contract. The agent doesn't get "write an ADR" as a free instruction; it gets a tool with named parameters. The difference shows at review time: structured output is comparable across projects, chat output isn't.
Tests guard the contract: pytest -q covers the CLI and the templates. Without it, a template edited with a formatting error would reach the agent and silently become a broken ADR — and a broken ADR is worse than a missing one, because it looks like it exists.
Decoupled frontend: the site in frontend/ is HTML/CSS/JS with no framework, with npm ci, lint and build as the whole cycle. It shares no code with the Python package; it's documentation and portfolio, published on Vercel through the Git integration.
What this repository is not
It is not a ready-made MCP server you plug into your client and forget, and it is not a reviewer that approves architecture on its own. The templates give shape; the decision is still yours. If the agent returns an ADR with no rejected alternatives or a threat model with no mitigation assigned to someone, the artifact is incomplete — treat it as a draft, not a record.
Why encode practice into a tool
After years reviewing financial system designs, the defect I saw most was not the wrong decision — it was the decision with no record. The system ships, the team turns over, and two years later nobody knows why the queue is FIFO or why the database is multi-region. The cost of that amnesia isn't writing the missing ADR; it's redoing the whole analysis under incident pressure.
AI agents make this worse or fix it, depending on how they come in. Come in as free chat, and the result is convincing prose nobody can compare with the previous project. Come in as a tool with a contract, and every output already carries title, context, decision and consequences in the same place every time.
Traceability: a CLI-generated ADR goes into git next to the code. git blame answers who decided and when.
Security review: a threat model on the standard template is comparable across projects; the reviewer knows where to look for the missing mitigation.
Cost as maintenance: the cost review workflow asks what the choice costs per year of operation — not what it costs in launch month.
The lesson behind the repository: a narrow tool produces an auditable artifact; broad chat produces text that looks like one.
FAQ
Do I need AWS credentials to use it?
No. The CLI calls no AWS API; the Well-Architected checklist is knowledge encoded in a template, not a query to the Well-Architected Tool service.
Which MCP client does it work with?
The repository documents the MCP-compatible tool design; wiring to a specific client depends on you exposing the CLI as a server. Read docs/architecture.md before assuming you can just point a client at it.
Why does HTML show as the primary language?
The static frontend in frontend/ weighs more in bytes than the Python package. The logic is in Python; the HTML is the portfolio surface on Vercel.
Can I change the ADR format?
Yes — edit the template in the package and run pytest -q. With pip install -e . the change applies immediately. Keep the tests passing or the broken output reaches the agent with no warning.
References
When to use it
Use it when: you already write ADRs and threat models by hand, want an AI agent to produce the first draft in your format, and need the result to be versionable and comparable across projects. It also works as a starting point if you're designing your own MCP tools and want an example of a narrow contract instead of free chat. Don't use it if you expect a ready-made MCP server or an automatic reviewer — the toolkit gives shape and discipline; the decision and the signature stay with you.
Architecture, AWS, AI and market deep dives — straight to your inbox. Free.
No spam · unsubscribe anytime