ArchScript MCP
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| ARCHSCRIPT_PORT | No | Port of the ArchScript MCP server. Defaults to 47621. | 47621 |
| ARCHSCRIPT_TOKEN | No | Access token from ArchScript → Settings → AI. Without it, or without ArchScript for Mac running, the bridge still answers introspection. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
ArchScript is an architecture-as-code app. The .archs source is the single source of truth; the diagram is generated from it. Workflow: call archscript_guide once to learn the language, then list_documents / get_document. Make changes with edit_document (structured operations, preferred for small changes) or set_document_source (whole file). Every change shows up live and undoable in the user's open window. Check results with the returned diagnostics and render_diagram. Use validate to try source without touching a document, and create_document to open a new architecture. Requires ArchScript for Mac with 'Allow AI assistants' turned on in Settings → AI.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| archscript_guideA | The ArchScript language: syntax, element types, containers (domain, boundary, environment, cluster, server, container), relations, properties, rules, custom types and the edit operations. Read this before writing ArchScript. |
| list_documentsA | Open ArchScript documents with id, file name, project name, validity and size. The first entry is the frontmost window. |
| get_documentA | Source code (with line numbers), diagnostics, metrics and the structure (containers, elements, relations with their indices) of a document. |
| create_documentB | Opens a new ArchScript window with the given source and returns its id and diagnostics. |
| set_document_sourceA | Replaces the whole source of a document (one undoable step in the user's window). Returns diagnostics. |
| edit_documentA | Applies structured edit operations in order (one undoable step). Each operation is an object with "op" and its fields: add_element {kind, name, container?} · add_relation {from, to, label?, bidirectional?} · set_property {element, key, value|null} · rename {element, name} · change_id {element, id} · change_kind {element, kind} · set_tags {element, tags[]} · move_to_container {element, container|null} · delete_element {element} · set_relation_label {relation, label|null} · set_relation_property {relation, key, value|null} · set_relation_direction {relation, direction: forward|reverse|both} · delete_relation {relation} · add_container {kind, name, container?} · rename_container {container, name} · delete_container {container} (keeps contents) · set_container_property {container, key, value|null} · set_container_color {container, color|null}. Elements are referenced by id, relations by index (see get_document), containers by key like "cluster:Prod/server:app-01". |
| validateA | Compiles ArchScript source without opening or changing a document: diagnostics, metrics and review score. |
| reviewB | Score, grade, metadata coverage, coupling and all rule findings of a document. |
| render_diagramB | The document's diagram as a PNG image (the last valid state). |
| exportC | Generated output of a valid document: mermaid, plantuml, markdown (documentation), json (model) or terraform_aws / terraform_azure / terraform_gcp. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 10 tools
Most tools have clearly distinct purposes, especially document CRUD versus export/render versus the guide. Some overlap exists: get_document, validate, and review all report diagnostics or metrics, and set_document_source versus edit_document both modify source, though their scopes differ.
Document operations mostly follow verb_noun naming such as list_documents, get_document, and create_document. However, export, validate, and review are bare verbs, while archscript_guide is an anomalous prefixed noun, making the overall convention mixed but still readable.
Ten tools is a well-scoped size for an architecture DSL server covering document lifecycle, editing, validation, review, export, rendering, and authoring guidance. No obvious tool feels redundant or trivially unnecessary.
The surface covers create/list/get/edit/validate/review/export/render plus a language guide, which is strong lifecycle coverage for ArchScript documents. Minor gaps include no document delete/close operation and no explicit open-by-file-path workflow.