switchplinth MCP server
Commit Oct 23, 2026Analyzes ADRs, RFCs, and design notes to map architectural decisions and preview the impact of alternative component choices.
Also known as bcmyguest/switchplinth
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 23, 2026
- License
- Apache-2.0
What is switchplinth MCP?
switchplinth analyzes ADRs, RFCs, and design notes to map architectural decisions and preview the impact of alternative component choices.
Summary generated from the project's README
About switchplinth MCP server
Visualizing architectural changes from existing documentation is what Switchplinth enables for engineering teams. By reading Markdown files such as ADRs, RFCs, and design notes, the tool maps technical decisions and the components they affect. It creates a system map and an architecture log that records why specific options were chosen and why alternatives were rejected, linking every inferred fact back to its original source passage.
Developers can use the What-if panel to preview the impact of switching components without modifying the actual repository. For example, switching from Kafka to Amazon SQS can trigger alerts if a service requires a capability like event replay that the new provider lacks. The system runs locally using Docker and Compose, and users can connect it to an AI client by running a setup wizard via uv. It supports extraction through a local Lemonade model or other OpenAI-compatible providers to turn text into structured YAML decisions stored in a .decision directory.
What you can do with it
- 1Preview component swapsAsk the AI to show how the system map changes if a different messaging provider is selected.
- 2Trace architectural reasoningInvestigate why a specific technology was chosen by querying the architecture log for source passages.
- 3Identify capability gapsDetermine if replacing a component will break a requirement like event replay.
- 4Audit decision historyReview a permanent record of all architectural decisions and their rejected alternatives.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 16, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablebcmyguest/switchplinth is public and reachablegithub.com/bcmyguest/switchplinth ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-23github.com/bcmyguest/switchplinth ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubSwitchplinth
Visualize architecture changes from the docs you already wrote.
Switchplinth reads your ADRs, RFCs, and design notes, maps the decisions and the components they touch, and shows what changes when you switch an option. Every inferred fact links to its source passage.
Write an ADR, run Discover, and the decision shows up in the Architecture log with its alternative and why it lost, joins the system map, and can be previewed the other way in What-if.

Step 2 of the recording names the extractor it used. scripts/record-workflow.sh records it with real extraction through a local Lemonade model; see Recording the workflow GIF.
Screenshots on this page are captured from the running app on the bundled food-delivery sample (fixture-tuned mock extraction) by site/scripts/app-screenshots.mjs and site/scripts/workflow-gif.mjs; the workflow's first step shows the ADR file as it is written.
Run it
You need Docker with Compose v2 and curl.
./scripts/demo.sh # build, load the food-delivery sample, start
./scripts/demo.sh --down # stop; --purge also deletes the sample
Then open http://localhost:3000. To extract with a local model, see model providers.
To point Switchplinth at your own repository and register its MCP server with your client, run cd backend && uv run switchplinth setup (setup wizard).
A closer look

The What-if panel previews another option without changing the repository's choice.

The Architecture log shows each decision's reason, its alternatives, and why they lost, quoted from the source.

Your reviews go into an append-only log, and each one can be undone.

Ask why, and the answer lists the source passages it found.

How it works
- Your Markdown is the input and is never modified.
- Extraction writes decisions, options, and components as YAML under
.decision/, each citing its passage. The demo's fixture-tuned mock needs no model. - You confirm, reject, or correct what was inferred. Each judgment is a new record, so re-extraction keeps your reviews.
- Each option is a typed change to one base graph. The compiler applies the selected options to draw the map.
- SQLite and Qdrant indexes are rebuilt from those files and can be deleted at any time.
More detail: docs/ARCHITECTURE.md.
Works today
- Markdown discovery, with no template required
- Fixture-tuned mock extraction, and extraction through a local OpenAI-compatible model (tested on small samples)
- The system map, decision options, and What-if previews
- Source passages behind every inferred claim
- Review of claims, aliases, and identities, with an append-only log and undo
- The Architecture log: reasons, rejected alternatives, and consequences
- Saved scenarios: create, list, and load
- Scenario diffs between any two selections, with relationship-based downstream impact (API and MCP); What-if shows the diff against the previous choice
- Capability requirements in scenarios: a component can require a capability such as event replay, and the diff reports when a switch leaves no reachable provider. Switching Kafka to SQS in the sample flags Order Service's replay requirement and names SQS as lacking it (API, MCP, and the Architecture map What-if overlay, which lists appeared and disappeared requirements under "Changes vs previous choice" and the current ones under "Compared with repository choices")
- Input receipts on graph, scenario, search, and diff results, for checking whether the inputs changed
- Search that cites its sources, and an MCP server over HTTP and stdio
- Indexes that rebuild from the files
Up next
- Testing hosted providers (OpenAI, Anthropic); the adapters exist but are untested
- Measuring extraction recall on more repositories
- Extraction beyond the fixture-tuned mock, which demonstrates the decision model, not extraction quality
- Authentication for remote API and MCP access (both listen on localhost only today)
- Source formats beyond Markdown
- Conflict detection beyond two options writing the same ID
- Renaming, updating, and deleting saved scenarios
Links
- Website and docs: https://bcmyguest.github.io/switchplinth/
- Getting started: https://bcmyguest.github.io/switchplinth/docs/getting-started/
- MCP tools: https://bcmyguest.github.io/switchplinth/docs/mcp/
- Development notes, full setup, and API behavior: docs/DEVELOPMENT.md
- Contributing and agent rules: AGENTS.md
- Portable file format: docs/PORTABLE_FORMAT.md
- Current plan: docs/V2_PLAN.md
Switchplinth is a work in progress. It was built by bcmyguest with AI assistance; coding agents wrote much of the code.
License
Apache-2.0. See LICENSE.
switchplinth MCP questions
How does Switchplinth handle my existing documentation?
It reads your existing ADRs, RFCs, and design notes in Markdown format without modifying them.
Can I see the reasoning behind architectural decisions?
Yes, the Architecture log shows the reason for each decision, its alternatives, and why they were not chosen, with direct quotes from your sources.
What happens if I want to test a different technology choice?
The What-if panel allows you to preview how a different option would change your system map without actually changing your repository's files.
How does the tool ensure the information it provides is accurate?
Every inferred fact or claim is linked directly to its source passage in your documentation.