Agent integration

Use the capability manifest before an agent constructs a BC Atlas command.

bca help --format json

The command writes versioned JSON to standard output. It defines command IDs, argument templates, options, output contracts, and exit codes.

Invocation rules

1. Pass each argument as a separate array item.
2. Do not construct a shell command string.
3. Use export --view <view> --format json, check --format json, architecture --format json, or docs ... --format json for machine reads.
4. Check for exit code 0 before you parse standard output.
5. Run docs set and docs unset with --dry-run first.
6. Pass --expected-hash when you write AL metadata.

Guided setup

bca setup agent --agent claude|copilot|cursor writes a /bca-setup command that lets the agent set up BC Atlas through the CLI: it reads bca setup plan --format json, asks the user, previews with bca setup apply --dry-run --format json, and applies after confirmation. bca setup agent without --agent prints the same instructions for any other agent. See Guided setup.

Source of truth

AL source is authoritative. JSON, Markdown, D2, and SVG files are generated outputs.

Read the generated capability summary for the current command list. Use bca help --format json for the complete machine contract.

MCP server

BC Atlas includes a local MCP server. Install the package, then configure your MCP host to start bca-mcp (or bca mcp; both start the same server).

In VS Code, the BC Atlas extension registers the server for you: agents in the editor (for example GitHub Copilot in agent mode) list BC Atlas among their MCP servers without any configuration.

.mcp.json example

Copy the MCP JSON example to the configuration location for your MCP host.

Architecture tools accept projectRoot separately from path. Set path to the folder that the agent should render and projectRoot to the app or multi-app workspace that it should analyze.

{
  "mcpServers": {
    "bc-atlas": {
      "command": "npx",
      "args": ["--yes", "--package", "bc-atlas", "bca-mcp"]
    }
  }
}

This configuration uses npx to get BC Atlas and start its bca-mcp executable.

If BC Atlas is installed globally, use this shorter configuration:

{
  "mcpServers": {
    "bc-atlas": {
      "command": "bca-mcp"
    }
  }
}

For a repository checkout, use an absolute source path:

{
  "mcpServers": {
    "bc-atlas": {
      "command": "node",
      "args": ["C:/path/to/BC-Atlas/src/mcp.js"]
    }
  }
}

The server uses stdio. It writes protocol messages to standard output and logs to standard error.

MCP tools

• bc_atlas_capabilities reads the command contract.
• bc_atlas_inspect returns an architecture model.
• bc_atlas_check returns the architecture health report used by bca check.
• bc_atlas_architecture returns the target architecture with work items (with the bca refactor command for moves), data ownership, and checks.
• bc_atlas_extraction_plan plans extracting one component as an app: blockers, app.json, data moves, and steps.
• bc_atlas_refactor_surface sets Access = Internal on objects no other component uses and writes exposes to .bca.json; dryRun by default.
• bc_atlas_refactor_move moves an object to another component with namespace and using fixes; dryRun (default) returns the diff, dryRun: false writes it. See Split a monolith into apps.
• bc_atlas_report writes the Markdown architecture report (bca export --view report).
• bc_atlas_setup_plan detects the project and returns setup questions with recommendations.
• bc_atlas_setup_apply previews (default) or writes .bca.json, Git hooks, and a pipeline.
• bc_atlas_run runs the tasks configured for a trigger and reports sync status.
• bc_atlas_update_check reports whether a newer BC Atlas version exists, with release notes.
• bc_atlas_generate_diagram writes D2, JSON, or SVG.
• bc_atlas_docs_list lists documented scenarios.
• bc_atlas_docs_show reads one scenario and its source hash.
• bc_atlas_docs_validate validates a documentation corpus.
• bc_atlas_docs_generate writes Markdown from AL UI tests.
• bc_atlas_docs_edit previews or applies one metadata change.
• bc_atlas_docs_glossary reads supported documentation tags.

bc_atlas_docs_edit uses preview mode by default. A real write requires dryRun: false and the latest expectedFileHash.

Test with MCP Inspector

Run the Inspector through npx:

npx @modelcontextprotocol/inspector bca-mcp

For a checkout, use this command:

npx @modelcontextprotocol/inspector node src/mcp.js