# Architect MCP server — standalone bundle

A single-file Model Context Protocol server (stdio transport) that exposes
the Architect language toolchain to an Agent client.

## What this is

`architect-mcp-standalone.js` is a self-contained ESM bundle: SDK,
parser, validators, registries, and agent-tool adapters all inlined. No
npm install required at the destination — only Node 20+.

The bundle does NOT include the SQL Server description-codes connector.
The two tools that depend on it (`lookup_description_code`,
`refresh_description_codes`) are filtered out at startup.

## How to launch

Bash / cmd-style shells:

```sh
ARCH_LANG_ROOT=/absolute/path/to/Reports node architect-mcp-standalone.js
```

PowerShell:

```powershell
$env:ARCH_LANG_ROOT = "C:\absolute\path\to\Reports"
node architect-mcp-standalone.js
```

In practice the MCP server is rarely launched directly — the agent
client (Claude Desktop, VS Code MCP host, etc.) spawns it from its own
config file, which has its own env-var syntax. The above are for manual
smoke-tests.

Optional environment:

- `ARCH_LANG_CONFIG` — absolute path to `.architect.json`. Defaults to
  `<ARCH_LANG_ROOT>/.architect.json` if present.
- `ARCH_LANG_TOOL_TIMEOUT_MS` — per-tool timeout (default 30000).
- `ARCH_LANG_LOG_PATH` — append-only diagnostic log file.

The server speaks stdio and never writes JSON-RPC framing to stderr;
configuration / status lines go to stderr only.

## Tools available

The standalone bundle registers 9 tools:

| Tool | Purpose |
|---|---|
| `list_files` | Inventory of `.TXT` files under configured scan roots. |
| `list_symbols` | Top-level + function-scoped symbols in a file. |
| `list_includes` | `#include` directives, optionally transitive. |
| `lookup_symbol` | Resolve a name to its declaration (4-tier). |
| `find_references` | Reads / writes / calls / definitions of a symbol, or includers of a file. |
| `find_impacts` | Reverse-include closure or per-file usage roll-up. |
| `list_literal_comparisons` | `STATUS = "A"`-style comparisons against literals. |
| `validate_file` | Full diagnostic suite, normalised output. |
| `list_suppressions` | `// @rule-ignore ACU-XXX-NNN` entries in a file. |

## File access

The server reads files via Node `fs` from `ARCH_LANG_ROOT`. There is no
content-injection tool: all inputs are file paths resolved against the
workspace root. Paths that escape the root are rejected with a structured
`{status:"unknown"}` response.

## Demo rule set

The shipped `.architect.json` enables only two rule families:

```json
{
  "rules": {
    "mode": "allowlist",
    "enabled": ["ACU-IND-*", "ACU-SQL-*"]
  }
}
```

This narrows the demo surface to index-cursor hygiene and SQL coding
standards. To widen, replace the `rules` block with `{ "mode": "all" }`
or remove it entirely (the default is `"all"`). Glob support: `*` matches
one or more of `[A-Z0-9-]`. Exact IDs (`ACU-SQL-001`) are accepted.

## Things to watch when bridging from a content store

These are observations, not warnings — the validators run against the
on-disk file as Node reads it:

- **Line endings** — diagnostics report 1-based line numbers. CRLF/LF
  mix-ups will not change line numbers, but tools that diff against a
  vector-store original may see spurious change.
- **Trailing whitespace** — preserved verbatim; some Architect rules
  notice it.
- **BOM** — the parser strips a leading UTF-8 BOM, but its presence
  shifts byte offsets if the calling agent indexes by them.
- **Chunk-boundary reassembly** — if files are reconstituted from a
  chunked store, ensure no chunk boundary falls inside a multi-byte
  character or an interpolation token (`@...@` by default; `^...^` when
  the file overrides the delimiter).
