Architect MCP

Architect MCP is the developer-facing MCP server for creating and managing Semantic Rails package projects. It is separate from the query MCP and does not start, stop, or reconfigure hosted cloud services.

Start the server

architect mcp

semantic-rails-architect-mcp --transport stdio
semantic-rails-architect-mcp --transport streamable-http --host 127.0.0.1 --port 8010

The default HTTP port is 8010, which keeps it away from the local Semantic Rails API server and the query MCP defaults.

From a source checkout, prefix the same commands with uv run.

Guided setup flow

Call architect_guidance for workflow and safety guidance.
Call project_status before editing an existing project.
Call setup_project_dialog to collect starter package answers.
Call create_project to scaffold a runnable split package.
Use upsert_model, upsert_metric, and upsert_segment for structured edits.
Run validate_project, then use impact_project or promotion_check with compare_path or base_ref.

Interactive dialogs

setup_project_dialog returns a structured question set for every MCP client. Clients that support MCP elicitation can set interactive=true and collect the same package answers in-client.

Tool reference

Tool	Role
`architect_guidance`	Return the recommended developer workflow and guardrails
`setup_project_dialog`	Collect starter package answers through a schema or MCP elicitation
`create_project`	Create a runnable `schema_version: 1` starter package
`project_status`	Inspect files, parse health, and optional runtime checks
`list_project_files`	List project files inside the configured workspace root
`read_project_file`	Read a UTF-8 package file by relative path
`write_project_file`	Write a scoped package file and optionally parse afterward
`upsert_model`	Update model YAML and the matching graph entity entry
`upsert_metric`	Create or update a curated metric recipe
`upsert_segment`	Create or update a governed segment definition
`archive_project_file`	Move a file into a project-local archive instead of deleting it
`validate_project`	Run parse, runtime, examples, tests, impact, or release checks
`diff_project`	Compare package behavior against another path or git base ref
`impact_project`	Summarize behavior changes, impacted metrics, reviewers, and risk
`promotion_check`	Run release readiness checks for a declared environment
`mcp_client_config`	Return command and URL hints for MCP client configuration

Scoped file tools

list_project_files, read_project_file, write_project_file, and archive_project_file operate inside the configured workspace root. Use --workspace-root when a client should work in a project directory outside this repository. Comparison paths for diff_project, impact_project, and release checks must also resolve to package directories inside that workspace root.

Validation modes

Mode	Use
`parse`	Fast authoring check without query execution
`runtime`	Compile and probe metrics through the active warehouse adapter
`examples`	Run package-local examples
`tests`	Run package-local semantic assertions
`impact`	Compare behavior against another package path or git base ref
`release`	Run promotion readiness checks for a declared environment

Runtime validation is operational. DuckDB checks can create or refresh a package database, and Snowflake checks can issue live queries through the configured Snow CLI connection.

Continue to Guardrails for runtime boundaries or API Reference for the query API.