MCP server

Let AI assistants validate, explain and dry-run smartcloud configs through the Model Context Protocol.

smartcloud-mcp is a Model Context Protocol (MCP) server. It lets an AI assistant, such as Claude Code, Cursor or VS Code’s Copilot agent, check and explain smartcloud configs by calling the same code as the action and the CLI, rather than guessing at them.

Why connect it: an assistant editing .github/smartcloud.yml can validate its change before suggesting it, explain why a check failed from the rule id, and check each commit message before committing, so its commits pass the commits check first time.

Every tool only reads. dry_run runs through the dry-run layer, so it lists the writes a run would make and never makes them. There is no doctor tool; run smartcloud doctor for that.

Connect it

The server speaks MCP over stdio. It needs Node 24 or later.

1. Add it to your client

   Most clients read an mcpServers map. From the first v2 release the server ships in the @resnovas/smartcloud npm package:

   .mcp.json

   {
     "mcpServers": {
       "smartcloud": {
         "command": "npx",
         "args": ["-y", "-p", "@resnovas/smartcloud", "smartcloud-mcp"]
       }
     }
   }
   

   Claude Code reads .mcp.json in the repository root; Cursor reads .cursor/mcp.json. With Claude Code you can also run claude mcp add smartcloud -- npx -y -p @resnovas/smartcloud smartcloud-mcp.

   Before that release, build it from a checkout (pnpm install && pnpm nx run @resnovas/smartcloud-mcp:build) and use "command": "node", "args": ["/path/to/smartcloud/apps/mcp/dist/main.js"].

2. Give it a token (optional)

   Tools that read GitHub (dry_run, plan_settings, and validating a config with extends) use GITHUB_TOKEN, or the token of the signed-in GitHub CLI (gh auth login). The token is resolved only when a tool needs GitHub, so validating a config without extends works offline.

3. Ask for it

   Start the server from the repository you work in, since config paths are read relative to it. Then ask, for example:

   • “Validate .github/smartcloud.yml with smartcloud.”
   • “Explain the smartcloud finding AI-02 and how to fix it.”
   • “Dry-run smartcloud on pull request 42 of my-org/my-repo with my local config.”
   • “Check this commit message with smartcloud before you commit.”

Tools

Tool	Input	What it returns
validate_config	config (YAML or JSON), optional source	Whether the config is valid once every extends preset is applied, with migration warnings. Strict, like smartcloud validate: unknown keys and invalid values are errors.
migrate_config	config (a v1 config.json), optional source	The v2 YAML, and a warning for everything not carried over.
explain_config	config, optional source	Which features the resolved config enables and the rules each one applies.
dry_run	repository (owner/name), one of pr, issue or event, optional config or configText, optional features	The run’s summary and the writes it would make.
plan_settings	repository, optional config or configText	Every repository settings step the config would apply.
check_commit_message	message, authorName, authorEmail, optional config	Whether a commit message passes the DCO and AI attribution rules, and every finding. An agent should call it before each commit.
explain_rule	rule (the id a finding reports, such as AI-02, DCO or conventions.title), optional config	What the rule asks for, how to satisfy it, and a link to the policy text.

event is one of schedule, push or workflow_dispatch. An empty features list runs every feature, as leaving it out does. Without config or configText, dry_run and plan_settings read the repository’s config from its default branch, as the action does.

Local config files

dry_run and plan_settings take the config to use in one of two ways:

• configText: the config itself, YAML or JSON. Prefer this: the server reads nothing from disk.
• config: a path to a config file. The server reads it only when the path is relative, resolves inside the directory the server was started in (after following symlinks), and names a regular file. Any other path is refused with a tool error, and nothing is read.

The restriction matters because these tools are marked read-only, so a client may run them without asking. Without it, an assistant steered by text it had read could have the server read any file the server’s user can.

Failures come back as tool errors with a message, never as protocol errors.