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 manage the self-hosted Semantic Rails cloud process.

Start the server

architect mcp

uv run semantic-rails-architect-mcp --transport stdio
uv run 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.

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 impact_project, then promotion_check.

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.