c4-architect-mcp 0.0.0-stage → 0.2.0-alpha.2

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+User-visible changes are recorded here. Unreleased work is not a published package or release.
+
+## 0.2.0-alpha.2 — 2026-11-06
+
+### Added
+
+- Render a focused neighborhood from a saved graph through `render_architecture_graph` or CLI `render --node`. Choose a direction and set depth, node, and relationship limits. Focused artifacts show the view's scope and include relationship source locations.
+
+### Fixed
+
+- Recognize TypeScript `export type *` re-exports as type-only dependencies.
+- Parse UTF-8, UTF-16LE, and UTF-16BE sources that start with a byte order mark and preserve the hash of the original bytes.
+- Report existing local assets reached through relative imports, TypeScript `paths` aliases, or `baseUrl` as unsupported local modules.
+- Compare snapshots across checkout directories and reconcile equivalent import spellings by resolved endpoints, kind, label, and protocol while preserving relationship multiplicity.
+
+## 0.2.0-alpha.1 — 2026-11-06
+
+### Added
+
+- A versioned graph foundation with source evidence, file hashes, explicit boundary mapping, diagnostics, summaries, bounded neighborhood queries, and graph comparisons.
+- Local TypeScript/TSX dependency analysis and module-resolution regression fixtures.
+- Compact server-side C4 image layout with orthogonal routing and compatible Mermaid source export.
+- PNG, SVG, Markdown, and self-contained interactive HTML artifacts.
+- Component and relationship selection, directional highlighting, keyboard controls, and full-diagram PNG/SVG exports preserving the current selection.
+- Synthetic 12-node and 20-node layout, interaction, and export regression cases.
+- Public-alpha documentation, contribution guidance, issue templates, a security policy, a code of conduct, and cross-platform CI configuration.
+- Direct CLI analysis, rendering, summaries, queries, and comparisons alongside the local MCP server.
+- Version-pinned npm/npx installation and client configuration instructions.
+- MIT licensing and dependency notices.
+
+### Clarified
+
+- Observed source dependencies, inferred classifications, and declared architecture boundaries are distinct.
+- Static imports do not prove runtime behavior, deployment boundaries, network protocols, or security properties.
+- Draw.io, Structurizr DSL, publishing, cross-repository mapping, additional languages, and assisted threat modeling remain roadmap items.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,11 @@
+# Code of Conduct
+
+Help keep this project useful and welcoming. Treat people with respect, explain your reasoning, and critique the work rather than the person. Different experience levels, backgrounds, and accessibility needs are welcome.
+
+Harassment, threats, discriminatory abuse, sexualized conduct, doxxing, and repeated personal attacks are not acceptable. Do not post another person's private information or contact them repeatedly after being asked to stop.
+
+Maintainers may edit or remove content, close a discussion, warn a participant, or restrict participation when needed to protect the community. They should explain decisions where practical and handle reports with care. This policy applies in project issues, pull requests, reviews, and other project-managed spaces.
+
+To report a concern, contact a maintainer through a private contact method listed on their GitHub profile. If none is available, open an issue requesting a private conduct-reporting channel without naming affected people or describing sensitive details publicly. Reports involving a maintainer should go to another maintainer when one is available.
+
+Good-faith disagreement, a rejected proposal, and a request for evidence are normal parts of collaboration. Keep the discussion focused, specific, and open to correction.

package/CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing
+
+Thanks for helping make code-derived architecture easier to inspect. This project is an alpha: focused fixes, reproducible examples, and clear limits are more useful than broad capability claims.
+
+## Start with a small case
+
+For a bug, include the smallest source fixture or graph that reproduces it, the expected result, the actual result, and relevant diagnostics. For a diagram problem, attach the full SVG or HTML when possible, along with a screenshot of the affected area.
+
+For a new parser, output format, or publishing integration, open a feature request before building a large change. Explain the user workflow, its relationship to the shared graph contract, and how it will be tested. The [roadmap](ROADMAP.md) gives the current direction.
+
+Do not include proprietary code, credentials, personal data, or internal hostnames in issues, fixtures, screenshots, or generated diagrams. Replace them with a small synthetic example that preserves the problem.
+
+## Local setup
+
+Use Node.js 22 or 24 and npm:
+
+```sh
+git clone https://github.com/zrack/c4-architect-mcp.git
+cd c4-architect-mcp
+npm ci
+npm test
+```
+
+`npm test` builds the server and runs the test suite. Use `npm run dev` to watch TypeScript changes. MCP clients launch the built `dist/index.js`; rebuild and reconnect the server before testing a change through a client.
+
+Run the browser checks when changing layout, SVG, HTML interaction, or exports:
+
+```sh
+npx playwright install chromium
+C4_BROWSER_CHANNEL=chromium npm run test:layout
+```
+
+On Linux, Playwright may need `npx playwright install --with-deps chromium`. In PowerShell, set `$env:C4_BROWSER_CHANNEL = "chromium"` before running the test. Installed Google Chrome is the default when this variable is absent.
+
+Generated fixtures and browser reports are under `output/playwright/component-scale/`. Review the actual images and selected exports as well as the test result.
+
+## Project map
+
+| Location | Responsibility |
+| --- | --- |
+| `src/index.ts` | MCP tool contracts and local artifact writes. |
+| `src/parsers/` | Source extraction and module resolution. |
+| `src/model/` | Versioned graph, boundary configuration, projections, and graph operations. |
+| `src/renderers/` | Mermaid export, compact layout, images, and interactive HTML. |
+| `test/` | Contract and regression tests with small fixtures. |
+| `scripts/` | Build, packaging, and browser verification helpers. |
+| `docs/images/` | Repository documentation artwork and generated examples. |
+
+## Keep the graph honest
+
+- An observed import is a code dependency. Do not turn it into a runtime protocol or deployment claim without supporting evidence.
+- Preserve source evidence and diagnostics when adding extraction or resolution behavior.
+- Keep declared boundaries separate from generated results. Stable IDs matter for rescans and comparisons.
+- Report unsupported or unresolved cases explicitly. Silently dropping an edge can make a diagram misleading.
+- Validate external input at the tool boundary, including duplicate identifiers and missing relationship endpoints.
+- Keep bounded query limits and truncation visible to callers.
+
+A parser fix should include a fixture that fails before the change and verifies the relevant edge, evidence, or diagnostic afterward. Avoid tests that simply repeat the implementation. A renderer fix should exercise the real output, including labels and interaction when affected.
+
+## Pull requests
+
+Keep a pull request focused enough to explain in a few paragraphs. Describe the concrete problem, resulting behavior, and relevant validation. Include a before/after image for visual changes and note any graph-schema or tool-contract changes.
+
+Before requesting review:
+
+1. Run `npm test`.
+2. Run `npm run test:package` for runtime dependencies, packaging, or CLI changes.
+3. Run `npm run test:layout` for renderer or interaction changes.
+4. Update examples and documentation affected by the change.
+5. Check that generated artifacts contain no private source or machine-specific paths.
+
+The CI workflow also checks Node.js 22 and 24 on Linux, macOS, and Windows. A local pass does not replace those platform results.
+
+AI-assisted contributions are welcome. You are responsible for understanding the change, checking its evidence, and verifying its behavior. Mention limitations that a reviewer should know.
+
+## License and conduct
+
+By contributing, you agree that your contribution may be distributed under the project's [MIT License](LICENSE). Submit only material you have the right to contribute. There is no separate contributor license agreement.
+
+Follow the [Code of Conduct](CODE_OF_CONDUCT.md). For a possible vulnerability, follow [SECURITY.md](SECURITY.md) instead of posting sensitive details in a public issue.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scott Zeitner and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,10 @@
+C4-Architect MCP Server
+Copyright (c) 2026 Scott Zeitner and contributors
+
+Project source and project-authored documentation are licensed under MIT.
+Dependencies retain their own licenses. See THIRD_PARTY_NOTICES.md and the
+license/notice files distributed with the installed dependency packages.
+
+C4 is a modeling approach created by Simon Brown. This is an independent
+project and is not affiliated with or endorsed by the C4 model, the Model
+Context Protocol project, OpenAI, Anthropic, or Eclipse.

package/README.md

@@ -1,3 +1,343 @@
-# Temporary Holding Version
+![C4 Architect — local source, reviewable evidence, readable diagrams](https://raw.githubusercontent.com/zrack/c4-architect-mcp/main/docs/images/hero.svg)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# C4 Architect
+
+**Explore a TypeScript codebase without pasting the whole repository into a prompt.**
+
+C4 Architect is a local [Model Context Protocol](https://modelcontextprotocol.io/) server that turns source imports into a versioned dependency graph, lets you review and name its architectural boundaries, and produces compact C4 diagrams. Use it from Codex, Claude Code, Claude Desktop, or another client that supports local MCP servers over `stdio`.
+
+**0.2.0-alpha.2 · TypeScript / TSX · Local parsing · MIT licensed**
+
+[Get started](#get-started) · [npm package](https://www.npmjs.com/package/c4-architect-mcp) · [See the diagrams](#read-the-diagram) · [Contribute](https://github.com/zrack/c4-architect-mcp/blob/main/CONTRIBUTING.md) · [Roadmap](https://github.com/zrack/c4-architect-mcp/blob/main/ROADMAP.md)
+
+![Workflow: parse local source, preserve evidence, declare boundaries, query and compare, render and export](https://raw.githubusercontent.com/zrack/c4-architect-mcp/main/docs/images/workflow.svg)
+
+## Start with evidence
+
+An import is evidence of a code dependency. It does not, by itself, prove that two modules are separately deployed services, that an SDK call uses a particular protocol, or that a data flow is secure.
+
+C4 Architect keeps that distinction visible. Source locations and content hashes support observed dependencies. Naming heuristics remain inferences. A separate boundary configuration records the systems, containers, and components that a person has declared. Rescanning the source preserves those declarations.
+
+The result is a starting point for application and solution architecture review. Runtime behavior, organization structure, and enterprise architecture still need other evidence.
+
+| Available in this alpha | Purpose |
+| --- | --- |
+| Local Tree-sitter analysis | Extract TypeScript and TSX dependencies without an LLM parsing the source files. |
+| Versioned graph and source evidence | Save a graph for review, with source locations, file hashes, and analysis diagnostics. |
+| Explicit boundary mapping | Give systems, containers, and components stable names through a separate configuration file. |
+| Summary, neighborhood queries, and comparison | Inspect a saved graph without returning the entire graph every time. |
+| Context, Container, and Component diagrams | Render a graph projection or a graph supplied by the caller. |
+| Compact PNG, SVG, and interactive HTML | Trace orthogonal connections, inspect relationship labels, and export a selected view. |
+
+Draw.io, Structurizr DSL, wiki publishing, cross-repository mapping, additional languages, and assisted threat modeling are **planned**, not implemented. See the [roadmap](https://github.com/zrack/c4-architect-mcp/blob/main/ROADMAP.md).
+
+## Get started
+
+Use Node.js 22 or 24 and npm. Run the pinned alpha without a checkout:
+
+```sh
+npx -y c4-architect-mcp@0.2.0-alpha.2 --help
+```
+
+The examples pin `0.2.0-alpha.2` for a repeatable setup. `c4-architect-mcp@alpha` follows the prerelease channel and currently selects `0.2.0-alpha.2`. npm's `latest` tag remains on `0.2.0-alpha.1`, the initial prerelease. There is no stable release yet.
+
+The server communicates over `stdio`; starting it without a subcommand waits for an MCP client rather than opening a browser page or an HTTP port. The following configurations let your client start it through `npx`.
+
+<details>
+<summary><strong>Codex</strong></summary>
+
+Add this to `~/.codex/config.toml`, or use the MCP server settings in the Codex desktop app:
+
+```toml
+[mcp_servers.c4-architect]
+command = "npx"
+args = ["-y", "c4-architect-mcp@0.2.0-alpha.2"]
+```
+
+You can also register it from the Codex CLI:
+
+```sh
+codex mcp add c4-architect -- npx -y c4-architect-mcp@0.2.0-alpha.2
+```
+
+Reconnect the server after configuration changes. See the [official Codex MCP setup guide](https://learn.chatgpt.com/docs/extend/mcp).
+
+</details>
+
+<details>
+<summary><strong>Claude Code</strong></summary>
+
+```sh
+claude mcp add --transport stdio c4-architect -- npx -y c4-architect-mcp@0.2.0-alpha.2
+```
+
+Use `/mcp` to inspect the connection. See the [official Claude Code MCP documentation](https://code.claude.com/docs/en/mcp).
+
+</details>
+
+<details>
+<summary><strong>Claude Desktop</strong></summary>
+
+Open **Settings → Developer → Edit Config** and merge this entry with your existing `mcpServers` configuration:
+
+```json
+{
+  "mcpServers": {
+    "c4-architect": {
+      "command": "npx",
+      "args": ["-y", "c4-architect-mcp@0.2.0-alpha.2"]
+    }
+  }
+}
+```
+
+Completely restart Claude Desktop after saving. For Windows JSON paths, use forward slashes or escape each backslash. See the [official local MCP server setup guide](https://modelcontextprotocol.io/docs/develop/connect-local-servers).
+
+</details>
+
+These are local `stdio` configurations. Verify the connection in your chosen client. If a desktop app cannot find `npx`, use the executable's absolute path. On Windows, a client that cannot launch `npx` directly can use `command: "cmd"` with `args: ["/c", "npx", "-y", "c4-architect-mcp@0.2.0-alpha.2"]`.
+
+### Optional global installation
+
+```sh
+npm install -g c4-architect-mcp@0.2.0-alpha.2
+c4-architect-mcp --help
+```
+
+With a global installation, use `c4-architect-mcp` as the MCP command with no arguments, or use it in place of the pinned `npx` command below. Use an absolute executable path if your desktop client's PATH differs from your terminal's.
+
+### Use the CLI directly
+
+You can analyze and render without an MCP client:
+
+```sh
+npx -y c4-architect-mcp@0.2.0-alpha.2 analyze /absolute/path/to/project/src --level Component --out /absolute/path/to/project/architecture.graph.json --summary
+npx -y c4-architect-mcp@0.2.0-alpha.2 summary /absolute/path/to/project/architecture.graph.json
+npx -y c4-architect-mcp@0.2.0-alpha.2 render /absolute/path/to/project/architecture.graph.json --out /absolute/path/to/project/ARCHITECTURE.md
+```
+
+Replace `/absolute/path/to/project` with your project's location. Open the generated `ARCHITECTURE.html` beside the Markdown to explore the diagram.
+
+For explicit compiler settings, add `--tsconfig /absolute/path/to/tsconfig.json` to `analyze`. The nearest `tsconfig.json` is otherwise discovered and read as data. Boundary configuration is loaded only when `--config` is supplied. The CLI also provides `query` and `diff` commands; `--help` lists their options.
+
+### Run from a checkout or try the sample
+
+Clone the repository to contribute, inspect the source, or try the included [synthetic order-service example](https://github.com/zrack/c4-architect-mcp/blob/main/examples/README.md):
+
+```sh
+git clone https://github.com/zrack/c4-architect-mcp.git
+cd c4-architect-mcp
+npm ci
+npm test
+node dist/index.js analyze examples/order-service/src --level Component --config examples/c4-architect.config.json --out output/order-service.graph.json --summary
+node dist/index.js render output/order-service.graph.json --out output/ORDER-SERVICE.md
+```
+
+`npm test` builds `dist/index.js` and runs the automated tests. Open `output/ORDER-SERVICE.html` to explore the sample. To connect an MCP client to your checkout, use `node` as the command and the absolute path to `dist/index.js` as its only argument. After changing TypeScript, run `npm run build` and reconnect the server to load the new code.
+
+## Analyze a project
+
+Ask your connected client:
+
+> Use c4-architect to analyze `/absolute/path/to/project/src` at the Component level. Save the graph to `/absolute/path/to/project/architecture.graph.json` and return a summary. Review the diagnostics and inferred boundaries, then use `render_architecture_graph` to save `/absolute/path/to/project/ARCHITECTURE.md`.
+
+The analysis tool accepts:
+
+```json
+{
+  "targetDir": "/absolute/path/to/project/src",
+  "c4Level": "Component",
+  "outputPath": "/absolute/path/to/project/architecture.graph.json",
+  "responseMode": "summary"
+}
+```
+
+`responseMode: "summary"` saves the complete graph locally and returns counts and status, keeping it out of the model's context until needed. It requires `outputPath`. The default `"graph"` mode returns the graph.
+
+Use absolute paths: an MCP client's working directory may differ from the repository you want to analyze. Check diagnostics before treating a missing edge as an absent dependency. Static analysis cannot resolve every computed import or establish every runtime connection.
+
+The current parser covers `.ts` and `.tsx`, excluding declaration files, dependency/build/output directories, and symlink trees. It uses one nearest or explicitly supplied `tsconfig.json` per scan; nested project configurations are not orchestrated automatically. Static imports, re-exports, and literal `import()` / `require()` dependencies are supported; computed dependencies and parse problems remain visible through diagnostics.
+
+Existing CSS, SVG, and other local assets found through relative imports, `paths` aliases, or `baseUrl` produce an `UNSUPPORTED_MODULE_TYPE` diagnostic. The graph contains the TypeScript/TSX dependencies. An unresolved specifier that matches a configured alias produces an `UNRESOLVED_IMPORT` diagnostic.
+
+To name architectural boundaries, supply `configPath` explicitly. The [example configuration](https://github.com/zrack/c4-architect-mcp/blob/main/examples/c4-architect.config.json) demonstrates the format:
+
+```json
+{
+  "schemaVersion": "1.0",
+  "system": { "id": "shop", "label": "Shop" },
+  "defaultContainer": {
+    "id": "application",
+    "label": "Application",
+    "technology": "TypeScript / Node.js"
+  },
+  "components": [
+    { "id": "orders", "label": "Order orchestration", "paths": ["orders"] },
+    { "id": "payments", "label": "Payments", "paths": ["payments"] }
+  ]
+}
+```
+
+`paths` are literal file or directory prefixes relative to `targetDir`, not globs. Give a component a `containerId` when mapping it into an explicitly configured container. Ambiguous matches are rejected. Unmapped files use the default container, which is inferred unless you configure it. Keep this configuration separate from the generated graph.
+
+```json
+{
+  "targetDir": "/absolute/path/to/project/src",
+  "c4Level": "Component",
+  "configPath": "/absolute/path/to/project/c4-architect.config.json",
+  "tsconfigPath": "/absolute/path/to/project/tsconfig.json",
+  "outputPath": "/absolute/path/to/project/architecture.graph.json",
+  "responseMode": "summary"
+}
+```
+
+## Inspect before drawing
+
+| Tool | Input | Result |
+| --- | --- | --- |
+| `analyze_architectural_boundaries` | `targetDir`, `c4Level`; optional `configPath`, `tsconfigPath`, `outputPath`, `responseMode` | A saved graph, full response, or compact summary at the requested C4 level. |
+| `get_architecture_summary` | `graphPath` | A compact overview of a saved graph and its diagnostics. |
+| `query_architecture_graph` | `graphPath`; optional `nodeId`, `search`, `direction`, `maxDepth`, `maxNodes`, `maxEdges`, `maxBytes`, `includeEvidence` | A bounded neighborhood or search, with truncation reported. |
+| `compare_architecture_graphs` | `beforePath`, `afterPath`; optional `limit`, `maxBytes` | Change counts and bounded details for snapshots at the same C4 level. |
+| `render_architecture_graph` | `graphPath`; optional `title`, `outputPath`, `focus` | Render a saved graph or a focused neighborhood. |
+| `render_c4_mermaid` | `title`, `c4Level`, `nodes`, `relationships`, optional `outputPath` | Mermaid source and a compact server-rendered PNG; saved SVG, PNG, HTML, and Markdown when requested. |
+
+Queries default to `direction: "both"`, `maxDepth: 1`, `maxNodes: 25`, `maxEdges: 50`, and `maxBytes: 16000`. Source evidence is opt-in. Start with a summary, then search for a component or request its incoming or outgoing dependencies. Smaller views are usually easier to review than a complete repository drawing.
+
+Render a saved graph directly:
+
+```json
+{
+  "graphPath": "/absolute/path/to/project/architecture.graph.json",
+  "outputPath": "/absolute/path/to/project/ARCHITECTURE.md"
+}
+```
+
+For caller-supplied graphs, `render_c4_mermaid` remains available. To adapt an analysis projection manually, preserve its `nodes` and convert its `edges`:
+
+```js
+const relationships = analysis.edges.map(edge => ({
+  from: edge.source,
+  to: edge.target,
+  label: edge.label,
+  technology: edge.protocol === "unknown" ? undefined : edge.protocol,
+}));
+```
+
+Analysis levels are `Context`, `Container`, and `Component`; renderer levels are `C4Context`, `C4Container`, and `C4Component`. Do not invent a protocol when the analysis has no evidence for it.
+
+### Focus a diagram on one node
+
+Use `query --search` to find the exact node ID for a focused diagram. These commands use the graph from the checkout example and show the outgoing dependencies of Order orchestration.
+
+```sh
+npx -y c4-architect-mcp@0.2.0-alpha.2 query output/order-service.graph.json --search "Order orchestration" --depth 0
+npx -y c4-architect-mcp@0.2.0-alpha.2 render output/order-service.graph.json --node component:orders --direction outgoing --out output/ORDER-SERVICE.outgoing.md
+```
+
+With `--node`, render defaults to both directions, depth 1, 25 nodes, and 50 relationships. Use `--direction incoming` or `--direction outgoing` to trace one direction. Set `--depth`, `--nodes`, and `--edges` to adjust the view. The diagram caption shows how much of the saved graph is included. The render result reports omitted nodes and relationships and whether a node or relationship limit was reached.
+
+The focused Markdown relationship table and interactive HTML details show up to three source locations per relationship. Use the saved graph for the full evidence.
+
+For MCP, pass `focus` to `render_architecture_graph`. Find the ID with `query_architecture_graph` using `search`.
+
+```json
+{
+  "graphPath": "/absolute/path/to/project/architecture.graph.json",
+  "outputPath": "/absolute/path/to/project/ARCHITECTURE.orders.md",
+  "focus": {
+    "nodeId": "component:orders",
+    "direction": "outgoing",
+    "maxDepth": 1,
+    "maxNodes": 25,
+    "maxEdges": 50
+  }
+}
+```
+
+## Read the diagram
+
+![Five-component order-service diagram derived from the checked-in TypeScript example](https://raw.githubusercontent.com/zrack/c4-architect-mcp/main/docs/images/component-example.png)
+
+*Five declared components and five source-observed dependencies from the checked-in [order-service example](https://github.com/zrack/c4-architect-mcp/blob/main/examples/README.md). The application is synthetic; the dependencies come from its actual source imports.*
+
+[Full-size PNG](https://raw.githubusercontent.com/zrack/c4-architect-mcp/main/docs/images/component-example.png) · [Scalable SVG](https://raw.githubusercontent.com/zrack/c4-architect-mcp/main/docs/images/component-example.svg)
+
+The server computes the image layout with ELK, compares horizontal and vertical arrangements, and reserves space for the wrapped labels it draws. PNG and SVG rendering do not require a browser at runtime. Mermaid remains a compatible source export; a client's Mermaid layout may differ from the server image.
+
+The saved graph preserves the system/container hierarchy. The current image renderer draws a flat view, with parent-container and inferred-boundary information in node descriptions rather than nested boundary boxes. Inspect those descriptions in the interactive view.
+
+Saving `ARCHITECTURE.md` also writes `ARCHITECTURE.svg`, `ARCHITECTURE.png`, and `ARCHITECTURE.html` beside it. The Markdown shows the PNG, links to the interactive view, includes a relationship table, and retains the Mermaid source in a collapsed section.
+
+<details>
+<summary><strong>Explore the larger 20-node renderer example</strong></summary>
+
+![Synthetic 20-node Component graph used to exercise compact routing and long relationship labels](https://raw.githubusercontent.com/zrack/c4-architect-mcp/main/docs/images/component-20.png)
+
+This separate stress fixture has 20 nodes and 35 relationships, including branching, cycles, shared dependencies, and long labels. Its connections are authored test data rather than extracted source dependencies.
+
+[Full-size PNG](https://raw.githubusercontent.com/zrack/c4-architect-mcp/main/docs/images/component-20.png) · [Scalable SVG](https://raw.githubusercontent.com/zrack/c4-architect-mcp/main/docs/images/component-20.svg)
+
+</details>
+
+![Interactive Component diagram with Order orchestration selected and its incoming and outgoing connections highlighted](https://raw.githubusercontent.com/zrack/c4-architect-mcp/main/docs/images/selection-example.png)
+
+*The 20-node stress fixture with Order orchestration selected, saved through the interactive view's export buttons.*
+
+[Full-size selected PNG](https://raw.githubusercontent.com/zrack/c4-architect-mcp/main/docs/images/selection-example.png) · [Scalable selected SVG](https://raw.githubusercontent.com/zrack/c4-architect-mcp/main/docs/images/selection-example.svg)
+
+Select a component to highlight outgoing connections in blue and incoming connections in brown. Other routes fade. Select a relationship ID to isolate that route and inspect its full label. Zoom, keyboard selection, Escape, and **Show all** help you move between details and the complete picture.
+
+![Interactive diagram toolbar with full-size PNG and SVG export buttons](https://raw.githubusercontent.com/zrack/c4-architect-mcp/main/docs/images/export-toolbar.png)
+
+**Export PNG** and **Export SVG** preserve the current selection and connection highlighting across the full diagram, regardless of zoom or scroll position. PNG exports at twice the diagram's natural dimensions; SVG remains scalable. The self-contained HTML works as a local file without contacting the MCP server or an external service.
+
+Automatic layout cannot make every graph readable at every size. Crossings can remain, and a large full-graph image may need zoom. Use selection and bounded graph queries to follow a particular change or dependency.
+
+See [image provenance and regeneration instructions](https://github.com/zrack/c4-architect-mcp/blob/main/docs/images/README.md) to reproduce these examples.
+
+## Local execution and data
+
+The parser reads local source files and does not call an LLM API. Generated diagrams and their interaction code are self-contained. Your MCP client receives the tool results, and its own settings determine whether those results are sent to a model or another service. Review those settings before analyzing private source.
+
+Analysis is static; it does not run the analyzed application's code. Output options write the requested graph and diagram files. See [SECURITY.md](https://github.com/zrack/c4-architect-mcp/blob/main/SECURITY.md) for the security scope and reporting process.
+
+## Develop and verify
+
+From a repository checkout:
+
+```sh
+npm ci
+npm test
+npm run test:package
+npm run test:layout
+```
+
+The regular tests cover parsing, graph contracts, graph operations, rendering, and MCP behavior. The package check exercises a packed installation. The layout check uses real browser geometry and downloads against synthetic 12-node and 20-node fixtures. It checks labels, routes, arrowheads, compactness, highlighting, keyboard controls, and selection-aware PNG/SVG exports.
+
+The layout check uses installed Google Chrome by default. To use Playwright Chromium:
+
+```sh
+npx playwright install chromium
+C4_BROWSER_CHANNEL=chromium npm run test:layout
+```
+
+For PowerShell, set `$env:C4_BROWSER_CHANNEL = "chromium"` before running the test. Browser reports and generated fixtures are written under `output/playwright/component-scale/`. These checks cover the included cases, not every possible graph topology.
+
+The [CI workflow](https://github.com/zrack/c4-architect-mcp/blob/main/.github/workflows/ci.yml) configures tests on Node.js 22 and 24 across Linux, macOS, and Windows, plus a Chromium layout job. See the [GitHub Actions runs](https://github.com/zrack/c4-architect-mcp/actions) for results.
+
+## Build this with us
+
+Useful contributions start with a concrete case: an import that resolves incorrectly, a boundary that is hard to express, or a diagram whose route is difficult to follow. Small, sanitized fixtures are especially valuable.
+
+- **Report a bug:** include a minimal input, expected result, diagnostics, and a screenshot for rendering problems.
+- **Improve analysis:** add source evidence and a regression fixture; keep observed facts separate from inference.
+- **Improve diagrams:** test the actual SVG and exported images, including selected views.
+- **Design an extension:** discuss its graph contract before adding a new language, renderer, or publisher.
+- **Improve documentation:** try the setup on your platform and client, and report the exact versions used.
+
+Read [CONTRIBUTING.md](https://github.com/zrack/c4-architect-mcp/blob/main/CONTRIBUTING.md), the [Code of Conduct](https://github.com/zrack/c4-architect-mcp/blob/main/CODE_OF_CONDUCT.md), and the [roadmap](https://github.com/zrack/c4-architect-mcp/blob/main/ROADMAP.md). Public API details may change during the alpha; preserve a copy of important graph snapshots and boundary configurations.
+
+## License
+
+C4 Architect is available under the [MIT License](https://github.com/zrack/c4-architect-mcp/blob/main/LICENSE). You may use, modify, and redistribute it, including commercially, subject to the license terms. Dependency licenses and attribution requirements remain applicable; see [NOTICE](https://github.com/zrack/c4-architect-mcp/blob/main/NOTICE) and [third-party notices](https://github.com/zrack/c4-architect-mcp/blob/main/THIRD_PARTY_NOTICES.md).

package/ROADMAP.md

@@ -0,0 +1,59 @@
+# Roadmap
+
+The goal is a dependable path from local code evidence to architecture views that people can inspect, correct, and maintain. A readable diagram matters, but so does knowing why a line exists and what it does not establish.
+
+This is a direction, not a release schedule. Features marked planned are not available in the current server.
+
+## 1. Trustworthy local foundation — current alpha
+
+The first release centers on TypeScript and TSX over local `stdio` MCP connections.
+
+- Extract dependencies locally with Tree-sitter and resolve supported modules using project configuration.
+- Preserve source locations, file hashes, parse diagnostics, and unresolved dependencies.
+- Separate observed source facts, inferred classifications, and declared architecture boundaries.
+- Keep manual mapping in a separate versioned configuration, with stable declared identifiers.
+- Save a versioned graph; summarize it, query a bounded neighborhood, and compare snapshots.
+- Render C4 Context, Container, and Component views, with compact PNG/SVG output and interactive connection highlighting.
+- Export full-size PNG/SVG images with the current selection.
+- Maintain parser, graph, MCP, package, and browser layout regression checks.
+- Prepare documentation, licensing, contribution guidance, and CI for a public alpha.
+
+The checked-in code and tests are the source of truth for supported cases. Public availability and package publication are separate release steps.
+
+## 2. Make repeated use practical — next
+
+Make the graph useful throughout a project's life, rather than treating each drawing as a fresh prompt.
+
+- Expand module-resolution fixtures from real, sanitized project examples.
+- Add incremental analysis and caching with explicit invalidation rules.
+- Improve graph slicing, search, and explanations for large repositories.
+- Make graph comparison useful in pull requests without treating every source edit as an architecture change.
+- Extend client and platform compatibility testing with reproducible reports.
+- Add a documented extension contract before accepting additional language parsers.
+
+Acceptance matters more than feature count: unresolved analysis must stay visible, repeated scans must retain declared identities, and bounded responses must report truncation.
+
+## 3. Editable formats and documentation delivery — planned
+
+Add outputs that reuse the same graph, hierarchy, identifiers, and evidence.
+
+- **Draw.io XML (`render_c4_drawio`):** editable diagrams with meaningful groups and preserved relationship labels.
+- **Structurizr DSL (`render_structurizr_dsl`):** validated workspace output with explicit C4 hierarchy.
+- **Publishing:** choose one initial target, such as an Azure DevOps wiki, before expanding to Confluence or Notion.
+
+Publishing needs a previewable change, predictable ownership of generated content, and credentials supplied outside the graph. Git-backed wiki delivery and API publishing are alternatives to evaluate, not promises of two simultaneous implementations.
+
+## 4. Distributed systems and assisted review — planned
+
+Code imports are only one source of architectural evidence. Larger views need explicit connections to contracts and infrastructure.
+
+- Combine repositories through a declared manifest with repository identities and revisions.
+- Add evidence from API contracts, deployment files, and service configuration before inferring inter-service links.
+- Support additional languages through tested parser extensions.
+- Explore assisted STRIDE review using declared trust boundaries and evidence-backed flows.
+
+Threat-model output would identify review questions and hypotheses. An import graph alone cannot prove exposed ports, unencrypted traffic, or exploitable vulnerabilities.
+
+## Propose a feature
+
+Open a feature request with a concrete workflow, a small example, the expected graph or view, and a way to test success. Prefer an extension of the shared graph contract over a renderer-specific interpretation of source code. See [CONTRIBUTING.md](CONTRIBUTING.md).

package/SECURITY.md

@@ -0,0 +1,27 @@
+# Security
+
+## Scope
+
+C4 Architect is a local `stdio` MCP server. It reads source files from the requested directory, analyzes them statically, and can write graph and diagram artifacts to requested paths. It does not execute the analyzed application's code. It is not a sandbox for untrusted clients or a vulnerability scanner.
+
+Treat access to the server as access to the local files its process can read and write. Use the MCP client's permissions and the operating system's process permissions to limit that access. Tool results can include source paths, dependency names, and architecture details; the client's data-handling settings apply after those results are returned.
+
+The parser runs locally without an LLM API call. Saved interactive HTML, SVG, and PNG assets are self-contained. These properties do not imply that an MCP host will keep tool responses on the machine.
+
+## Supported versions
+
+Security fixes target the latest alpha code. Older alpha snapshots are not maintained separately. Rebuild and reconnect a local server after updating it.
+
+## Report a vulnerability
+
+Use [GitHub's private vulnerability reporting](https://github.com/zrack/c4-architect-mcp/security/advisories/new) when it is enabled for this repository. If private reporting is unavailable, open an issue asking the maintainer for a private reporting channel **without including the vulnerability details, a working exploit, credentials, or private source**.
+
+Include the affected revision, platform and Node.js version, a minimal reproduction, expected impact, and any relevant generated artifact. A sanitized local example is preferable to production data.
+
+Do not test against another person's repository, client, or infrastructure without their authorization. The project has no paid bug-bounty program or guaranteed response time.
+
+## Areas that matter
+
+Security-sensitive changes include source traversal and module resolution, output-path handling, package installation behavior, graph input validation, escaping untrusted labels in Mermaid/XML/HTML, and standalone HTML export behavior. Changes that introduce network access, application-code execution, credentials, or publishing require an explicit design and documentation update.
+
+Architecture classification and future threat-model features are analysis aids. They must not present inferred runtime connections or possible security concerns as verified vulnerabilities.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,21 @@
+# Third-party notices
+
+C4-Architect's own source is MIT licensed. That does not relicense its dependencies. npm installs those packages separately with their upstream license and notice files. Keep those notices when redistributing dependencies or bundling the application.
+
+The direct runtime dependencies in this alpha are:
+
+| Dependency | Version | Upstream license |
+|---|---|---|
+| `@modelcontextprotocol/sdk` | 1.32.2 | MIT |
+| `tree-sitter` | 0.21.1 | MIT |
+| `tree-sitter-typescript` | 0.21.2 | MIT |
+| `zod` | 4.6.7 | MIT |
+| `typescript` | 5.9.3 | Apache-2.0 |
+| `elkjs` | 0.12.1 | EPL-2.0 OR GPL-3.0-or-later |
+| `sharp` | 0.35.5 | Apache-2.0 |
+
+Use the EPL-2.0 option for ELK.js in this distribution. Its upstream license is included in `node_modules/elkjs/LICENSE.md`. This project does not modify or vendor ELK.js source.
+
+Sharp's optional native dependencies depend on platform and installation choices. The tested macOS ARM64 installation includes `@img/sharp-libvips-darwin-arm64` 1.3.4 under LGPL-3.0-or-later. Read the package's bundled notices and Sharp's [installation and licensing documentation](https://sharp.pixelplumbing.com/install/), including the notices for libvips and its libraries, before redistributing native binaries.
+
+The lockfile records transitive packages. Their licenses are provided in each installed package; this table is a direct-dependency guide, not an exhaustive replacement for upstream notices. Development tools (including Mermaid and Playwright) are not bundled in the runtime package. Generated diagrams are not assigned a separate license by this tool; their content may reflect the source or model supplied by the user.