@guildai/cli 0.5.9 → 0.5.10

package/README.md

@@ -210,8 +210,35 @@ guild version                           # Show version info
 ### Coding Assistant Skills
 
 ```bash
-guild setup                             # Install Guild skills for coding assistants
+guild setup                             # Install skills + configure MCP server
 guild setup --claude-md                 # Also create a CLAUDE.md template
+guild setup --no-mcp                    # Install skills only, skip MCP configuration
+guild mcp                               # Start MCP server (used by Claude Code, etc.)
+```
+
+### MCP Server
+
+The CLI includes an [MCP](https://modelcontextprotocol.io/) server that exposes Guild's API to AI coding assistants like Claude Code.
+
+**Setup:**
+
+```bash
+guild setup
+```
+
+This installs Claude Code skills and adds a `guild` entry to `.mcp.json` in your project. Claude Code (and other MCP-compatible tools) will automatically connect when they detect it.
+
+**What it provides:**
+
+- 24 tools: workspaces, agents, sessions, triggers, contexts, credentials
+- 2 resources: current workspace info and installed agents
+- All tools use your `guild auth` credentials automatically
+
+**Manual start (for debugging):**
+
+```bash
+guild mcp
+guild mcp --debug    # Verbose logging to stderr
 ```
 
 ## Configuration

package/dist/commands/setup.js

@@ -60,8 +60,8 @@ async function setupMcp(options) {
         const content = await fs.readFile(mcpPath, 'utf-8');
         existing = JSON.parse(content);
         if (existing.mcpServers && 'guild' in existing.mcpServers && !options.force) {
-            output.progress('Guild MCP server already configured in .mcp.json');
-            return;
+            output.progress('.mcp.json already has Guild server (use --force to overwrite)');
+            return 'skipped';
         }
     }
     const updated = {
@@ -78,6 +78,7 @@ async function setupMcp(options) {
     else {
         output.success('Created .mcp.json with Guild MCP server');
     }
+    return 'created';
 }
 async function setup(options) {
     const output = createOutputWriter();
@@ -116,7 +117,13 @@ async function setup(options) {
     }
     // Handle --mcp flag
     if (options.mcp) {
-        await setupMcp({ force: options.force });
+        const result = await setupMcp({ force: options.force });
+        if (result === 'created') {
+            filesCreated++;
+        }
+        else {
+            filesSkipped++;
+        }
     }
     // Handle CLAUDE.md template
     if (options.claudeMd) {
@@ -155,7 +162,7 @@ export function createSetupCommand() {
         .description('Set up Guild CLI skills for coding assistants (Claude Code, etc.)')
         .option('--force', 'Overwrite existing skill files', false)
         .option('--claude-md', 'Also create a CLAUDE.md template in the project root', false)
-        .option('--mcp', 'Configure Guild MCP server in .mcp.json', false)
+        .option('--no-mcp', 'Skip MCP server configuration')
         .action(async (options) => {
         await setup(options);
     });

package/docs/CLI_WORKFLOW.md

@@ -7,6 +7,12 @@ description: Agent development using the Guild CLI. Activated when user mentions
 
 For local agent development using the Guild CLI. This workflow manages agent code via the Guild git server.
 
+## MCP vs CLI
+
+If Guild MCP tools are available (check for tools prefixed with `guild_`), use them for **read operations**: searching agents, listing workspaces, reading contexts, checking sessions, viewing credentials. MCP tools are faster and don't require shell execution.
+
+Use the **CLI** (via Bash) for **local development operations**: `guild agent create`, `guild agent save`, `guild agent test`, `guild agent pull`, `guild agent clone`. These involve the local filesystem and git, which MCP can't do.
+
 ## CRITICAL: Always Use the Guild CLI
 
 **NEVER manually create agent files or use raw git commands.**

package/docs/DESIGN.md

@@ -190,6 +190,8 @@ Environments are Docker containers managed by GuildCore. The CLI provides a simp
 
 The CLI integrates with AI coding assistants like Claude Code, Cursor, and others. Run `guild setup` to install Guild skills into your project.
 
+The CLI also exposes a [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server via `guild mcp`. This gives coding assistants direct access to Guild's API — searching agents, managing workspaces, reading contexts, and starting sessions — without leaving the editor. `guild setup` configures it by default; use `--no-mcp` to skip.
+
 **Typical Workflow:**
 
 1. Initialize agent: `guild agent init --name my-agent --template LLM`

package/docs/skills/agent-dev.md

@@ -7,6 +7,12 @@ description: Local agent development using the Guild CLI. Activated when user me
 
 Build agents for Guild using the CLI. **Always use the Guild CLI for agent operations - never use raw git commands.**
 
+## MCP vs CLI
+
+If Guild MCP tools are available (check for tools prefixed with `guild_`), use them for **read operations**: searching agents, listing workspaces, reading contexts, checking sessions, viewing credentials. MCP tools are faster and don't require shell execution.
+
+Use the **CLI** (via Bash) for **local development operations**: `guild agent create`, `guild agent save`, `guild agent test`, `guild agent pull`, `guild agent clone`. These involve the local filesystem and git, which MCP can't do.
+
 ## When to Use This
 
 Activate when user:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guildai/cli",
-  "version": "0.5.9",
+  "version": "0.5.10",
   "description": "Guild.ai CLI - Build, test, and deploy AI agents",
   "type": "module",
   "main": "dist/index.js",