@guildai/cli 0.5.8 → 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/dist/mcp/tools.d.ts

@@ -1,4 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { GuildAPIClient } from '../lib/api-client.js';
-export declare function registerTools(server: McpServer, apiClient: GuildAPIClient, workspaceId: string, debug: boolean): void;
+export declare function registerTools(server: McpServer, apiClient: GuildAPIClient, defaultWorkspaceId: string, debug: boolean): void;
 //# sourceMappingURL=tools.d.ts.map

package/dist/mcp/tools.js

@@ -84,9 +84,16 @@ function errText(action, error) {
     return `Failed to ${action}: ${error instanceof Error ? error.message : String(error)}`;
 }
 // ---------------------------------------------------------------------------
+// Shared schema fragments
+// ---------------------------------------------------------------------------
+const workspaceIdParam = z
+    .string()
+    .optional()
+    .describe('Workspace ID (defaults to current workspace)');
+// ---------------------------------------------------------------------------
 // Tool registration
 // ---------------------------------------------------------------------------
-export function registerTools(server, apiClient, workspaceId, debug) {
+export function registerTools(server, apiClient, defaultWorkspaceId, debug) {
     // =========================================================================
     // User
     // =========================================================================
@@ -139,12 +146,9 @@ export function registerTools(server, apiClient, workspaceId, debug) {
         }
     });
     server.tool('guild_get_workspace', 'Get workspace details including context', {
-        workspace_id: z
-            .string()
-            .optional()
-            .describe('Workspace ID (defaults to current workspace)'),
+        workspace_id: workspaceIdParam,
     }, async ({ workspace_id }) => {
-        const wsId = workspace_id || workspaceId;
+        const wsId = workspace_id || defaultWorkspaceId;
         debugLog(debug, `guild_get_workspace: ${wsId}`);
         try {
             const ws = await apiClient.get(`/workspaces/${wsId}`);
@@ -163,12 +167,14 @@ export function registerTools(server, apiClient, workspaceId, debug) {
             };
         }
     });
-    server.tool('guild_list_workspace_agents', 'List agents installed in the current workspace', {
+    server.tool('guild_list_workspace_agents', 'List agents installed in a workspace', {
+        workspace_id: workspaceIdParam,
         search: z.string().optional().describe('Filter agents by name'),
-    }, async ({ search }) => {
-        debugLog(debug, `guild_list_workspace_agents: search=${search || ''}`);
+    }, async ({ workspace_id, search }) => {
+        const wsId = workspace_id || defaultWorkspaceId;
+        debugLog(debug, `guild_list_workspace_agents: ws=${wsId} search=${search || ''}`);
         try {
-            let endpoint = `/workspaces/${workspaceId}/workspace_agents`;
+            let endpoint = `/workspaces/${wsId}/workspace_agents`;
             if (search)
                 endpoint += `?search=${encodeURIComponent(search)}`;
             const agents = await apiClient.fetchAll(endpoint);
@@ -194,12 +200,14 @@ export function registerTools(server, apiClient, workspaceId, debug) {
             };
         }
     });
-    server.tool('guild_add_workspace_agent', 'Install an agent in the current workspace', {
+    server.tool('guild_add_workspace_agent', 'Install an agent in a workspace', {
         agent_id: z.string().describe('The agent ID to install'),
-    }, async ({ agent_id }) => {
-        debugLog(debug, `guild_add_workspace_agent: ${agent_id}`);
+        workspace_id: workspaceIdParam,
+    }, async ({ agent_id, workspace_id }) => {
+        const wsId = workspace_id || defaultWorkspaceId;
+        debugLog(debug, `guild_add_workspace_agent: ${agent_id} ws=${wsId}`);
         try {
-            const wa = await apiClient.post(`/workspaces/${workspaceId}/workspace_agents`, { agent_id });
+            const wa = await apiClient.post(`/workspaces/${wsId}/workspace_agents`, { agent_id });
             return {
                 content: [
                     {
@@ -245,7 +253,8 @@ export function registerTools(server, apiClient, workspaceId, debug) {
     // =========================================================================
     // Contexts
     // =========================================================================
-    server.tool('guild_list_contexts', 'List context versions for the current workspace', {
+    server.tool('guild_list_contexts', 'List context versions for a workspace', {
+        workspace_id: workspaceIdParam,
         limit: z
             .number()
             .int()
@@ -253,10 +262,11 @@ export function registerTools(server, apiClient, workspaceId, debug) {
             .max(100)
             .optional()
             .describe('Max results (default 20)'),
-    }, async ({ limit }) => {
-        debugLog(debug, 'guild_list_contexts');
+    }, async ({ workspace_id, limit }) => {
+        const wsId = workspace_id || defaultWorkspaceId;
+        debugLog(debug, `guild_list_contexts: ws=${wsId}`);
         try {
-            const response = await apiClient.get(`/workspaces/${workspaceId}/contexts?limit=${limit || 20}`);
+            const response = await apiClient.get(`/workspaces/${wsId}/contexts?limit=${limit || 20}`);
             const text = response.items
                 .map((c) => {
                 const summary = c.summary ? ` — ${c.summary}` : '';
@@ -302,22 +312,24 @@ export function registerTools(server, apiClient, workspaceId, debug) {
             };
         }
     });
-    server.tool('guild_publish_context', 'Create or publish a new context version for the workspace', {
+    server.tool('guild_publish_context', 'Create or publish a new context version for a workspace', {
         content: z.string().describe('The context content to publish'),
+        workspace_id: workspaceIdParam,
         status: z
             .enum(['ACTIVE', 'ARCHIVED'])
             .optional()
             .describe('Context status (default ACTIVE)'),
         summary: z.string().optional().describe('Short summary of the context'),
-    }, async ({ content, status, summary }) => {
-        debugLog(debug, 'guild_publish_context');
+    }, async ({ content, workspace_id, status, summary }) => {
+        const wsId = workspace_id || defaultWorkspaceId;
+        debugLog(debug, `guild_publish_context: ws=${wsId}`);
         try {
             const body = { manual_context: content };
             if (status)
                 body.status = status;
             if (summary)
                 body.summary = summary;
-            const ctx = await apiClient.post(`/workspaces/${workspaceId}/contexts`, body);
+            const ctx = await apiClient.post(`/workspaces/${wsId}/contexts`, body);
             return {
                 content: [
                     {
@@ -484,8 +496,10 @@ export function registerTools(server, apiClient, workspaceId, debug) {
             .string()
             .optional()
             .describe('Agent identifier (e.g. owner/agent-name). Uses workspace default if not specified'),
-    }, async ({ message, agent }) => {
-        debugLog(debug, `guild_chat: message="${message}", agent=${agent || 'default'}`);
+        workspace_id: workspaceIdParam,
+    }, async ({ message, agent, workspace_id }) => {
+        const wsId = workspace_id || defaultWorkspaceId;
+        debugLog(debug, `guild_chat: message="${message}", agent=${agent || 'default'}, ws=${wsId}`);
         try {
             const body = {
                 session_type: 'chat',
@@ -494,7 +508,7 @@ export function registerTools(server, apiClient, workspaceId, debug) {
             if (agent) {
                 body.agent_id = agent;
             }
-            const session = await apiClient.post(`/workspaces/${workspaceId}/sessions`, body);
+            const session = await apiClient.post(`/workspaces/${wsId}/sessions`, body);
             debugLog(debug, `Session created: ${session.id}`);
             const response = await pollForResponse(apiClient, session.id, debug);
             return {
@@ -530,7 +544,8 @@ export function registerTools(server, apiClient, workspaceId, debug) {
             };
         }
     });
-    server.tool('guild_list_sessions', 'List recent sessions in the current Guild workspace', {
+    server.tool('guild_list_sessions', 'List recent sessions in a Guild workspace', {
+        workspace_id: workspaceIdParam,
         limit: z
             .number()
             .int()
@@ -538,11 +553,12 @@ export function registerTools(server, apiClient, workspaceId, debug) {
             .max(100)
             .optional()
             .describe('Number of sessions to return (default 20)'),
-    }, async ({ limit }) => {
-        debugLog(debug, 'guild_list_sessions');
+    }, async ({ workspace_id, limit }) => {
+        const wsId = workspace_id || defaultWorkspaceId;
+        debugLog(debug, `guild_list_sessions: ws=${wsId}`);
         try {
             const queryLimit = limit || 20;
-            const response = await apiClient.get(`/workspaces/${workspaceId}/sessions?limit=${queryLimit}`);
+            const response = await apiClient.get(`/workspaces/${wsId}/sessions?limit=${queryLimit}`);
             const text = response.items
                 .map((s) => `• ${s.id} (${s.session_type}) — ${s.created_at}`)
                 .join('\n');
@@ -659,7 +675,8 @@ export function registerTools(server, apiClient, workspaceId, debug) {
     // =========================================================================
     // Triggers
     // =========================================================================
-    server.tool('guild_list_triggers', 'List triggers configured in the current workspace', {
+    server.tool('guild_list_triggers', 'List triggers configured in a workspace', {
+        workspace_id: workspaceIdParam,
         limit: z
             .number()
             .int()
@@ -667,10 +684,11 @@ export function registerTools(server, apiClient, workspaceId, debug) {
             .max(100)
             .optional()
             .describe('Max results (default 20)'),
-    }, async ({ limit }) => {
-        debugLog(debug, 'guild_list_triggers');
+    }, async ({ workspace_id, limit }) => {
+        const wsId = workspace_id || defaultWorkspaceId;
+        debugLog(debug, `guild_list_triggers: ws=${wsId}`);
         try {
-            const response = await apiClient.get(`/workspaces/${workspaceId}/triggers?limit=${limit || 20}`);
+            const response = await apiClient.get(`/workspaces/${wsId}/triggers?limit=${limit || 20}`);
             const text = response.items
                 .map((t) => {
                 const agent = t.agent.full_name || t.agent.name;
@@ -694,6 +712,7 @@ export function registerTools(server, apiClient, workspaceId, debug) {
     });
     server.tool('guild_get_trigger_sessions', 'List sessions spawned by a specific trigger', {
         trigger_id: z.string().describe('The trigger ID'),
+        workspace_id: workspaceIdParam,
         limit: z
             .number()
             .int()
@@ -701,10 +720,11 @@ export function registerTools(server, apiClient, workspaceId, debug) {
             .max(100)
             .optional()
             .describe('Max results (default 20)'),
-    }, async ({ trigger_id, limit }) => {
-        debugLog(debug, `guild_get_trigger_sessions: ${trigger_id}`);
+    }, async ({ trigger_id, workspace_id, limit }) => {
+        const wsId = workspace_id || defaultWorkspaceId;
+        debugLog(debug, `guild_get_trigger_sessions: ${trigger_id} ws=${wsId}`);
         try {
-            const response = await apiClient.get(`/workspaces/${workspaceId}/sessions?trigger_id=${trigger_id}&limit=${limit || 20}`);
+            const response = await apiClient.get(`/workspaces/${wsId}/sessions?trigger_id=${trigger_id}&limit=${limit || 20}`);
             const text = response.items
                 .map((s) => `• ${s.id} (${s.session_type}) — ${s.created_at}`)
                 .join('\n');

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.8",
+  "version": "0.5.10",
   "description": "Guild.ai CLI - Build, test, and deploy AI agents",
   "type": "module",
   "main": "dist/index.js",