@girardmedia/bootspring 1.1.0

package/mcp/server.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+
+/**
+ * Bootspring MCP Server
+ * Model Context Protocol server for AI assistant integration
+ *
+ * @package bootspring
+ * @module mcp
+ */
+
+const { TOOLS, RESOURCES, toolHandlers, resourceHandlers, trackTelemetry } = require('./registry');
+
+/**
+ * Create and start the MCP server
+ */
+async function main() {
+  const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+  const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+  const {
+    CallToolRequestSchema,
+    ListToolsRequestSchema,
+    ListResourcesRequestSchema,
+    ReadResourceRequestSchema
+  } = require('@modelcontextprotocol/sdk/types.js');
+
+  const server = new Server(
+    {
+      name: 'bootspring',
+      version: '1.1.0'
+    },
+    {
+      capabilities: {
+        tools: {},
+        resources: {}
+      }
+    }
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools: TOOLS };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    const handler = toolHandlers[name];
+    if (!handler) {
+      throw new Error(`Unknown tool: ${name}`);
+    }
+
+    try {
+      return await handler(args || {});
+    } catch (error) {
+      return {
+        content: [{
+          type: 'text',
+          text: `Error: ${error.message}`
+        }],
+        isError: true
+      };
+    }
+  });
+
+  server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    return { resources: RESOURCES };
+  });
+
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const { uri } = request.params;
+
+    const handler = resourceHandlers[uri];
+    if (!handler) {
+      throw new Error(`Unknown resource: ${uri}`);
+    }
+
+    return await handler();
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  console.error('Bootspring MCP server started');
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error('Failed to start MCP server:', error);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  TOOLS,
+  RESOURCES,
+  toolHandlers,
+  resourceHandlers,
+  trackTelemetry,
+  main
+};

package/mcp/tools/agent-tool.js

@@ -0,0 +1,137 @@
+/**
+ * MCP agent tool module
+ */
+
+function getToolDefinition() {
+  return {
+    name: 'bootspring_agent',
+    description: 'Work with specialized AI agents. List available agents, show details, or invoke for specialized expertise.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['list', 'show', 'invoke', 'search'],
+          description: 'Action: list agents, show details, invoke agent, or search'
+        },
+        name: {
+          type: 'string',
+          description: 'Agent name (e.g., database-expert, security-expert)'
+        },
+        topic: {
+          type: 'string',
+          description: 'Topic or question for the agent (when invoking)'
+        },
+        query: {
+          type: 'string',
+          description: 'Search query (when searching)'
+        },
+        includeExternal: {
+          type: 'boolean',
+          description: 'Include external skills catalog (skills/external) in list/search/show'
+        },
+        limit: {
+          type: 'number',
+          description: 'Max number of results for list/search when includeExternal is true'
+        }
+      },
+      required: ['action']
+    }
+  };
+}
+
+function createHandler({ agentModule, format }) {
+  return async (args) => {
+    const { action, name, topic, query } = args;
+
+    switch (action) {
+      case 'list': {
+        const agents = Object.entries(agentModule.AGENTS).map(([id, agent]) => ({
+          id,
+          name: agent.name,
+          category: agent.category,
+          description: agent.description
+        }));
+        return format.list({
+          title: 'Available Agents',
+          items: agents,
+          formatter: (a) => `   🤖 ${a.id}\n      ${a.name} - ${a.description.slice(0, 60)}...`,
+          hints: [
+            'Use action=show name="agent-id" to see full details',
+            'Use action=invoke name="agent-id" topic="your question"'
+          ]
+        });
+      }
+      case 'show': {
+        if (!name) return format.error('Agent name required', ['Provide name="agent-id"']);
+        const agent = agentModule.AGENTS[name];
+        if (!agent) return format.error(`Agent not found: ${name}`, [
+          'Use action=list to see available agents'
+        ]);
+        return format.agentDetails(name, agent);
+      }
+      case 'invoke': {
+        if (!name) throw new Error('Agent name required');
+        const agent = agentModule.AGENTS[name];
+        if (!agent) throw new Error(`Agent not found: ${name}`);
+
+        const contextText = `
+## Agent: ${agent.name}
+
+You are now acting as the **${agent.name}**, a specialized expert in:
+${agent.expertise.map(e => `- ${e}`).join('\n')}
+
+### Your Role
+${agent.description}
+
+### Guidelines
+1. Focus on your areas of expertise listed above
+2. Provide specific, actionable advice
+3. Include code examples when relevant
+4. Consider security and best practices
+5. Reference official documentation when helpful
+
+### Topic
+${topic || 'The user will provide context for your assistance.'}
+
+---
+
+Please provide your expert analysis and recommendations.
+`;
+        return {
+          content: [{
+            type: 'text',
+            text: contextText
+          }]
+        };
+      }
+      case 'search': {
+        if (!query) throw new Error('Search query required');
+        const queryLower = query.toLowerCase();
+        const matches = Object.entries(agentModule.AGENTS)
+          .filter(([id, agent]) => {
+            return id.includes(queryLower) ||
+              agent.name.toLowerCase().includes(queryLower) ||
+              agent.description.toLowerCase().includes(queryLower) ||
+              agent.expertise.some(e => e.toLowerCase().includes(queryLower)) ||
+              agent.triggers.some(t => t.includes(queryLower));
+          })
+          .map(([id, agent]) => ({ id, name: agent.name, description: agent.description }));
+
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify(matches, null, 2)
+          }]
+        };
+      }
+      default:
+        throw new Error(`Unknown action: ${action}`);
+    }
+  };
+}
+
+module.exports = {
+  getToolDefinition,
+  createHandler
+};

package/mcp/tools/capabilities-tool.js

@@ -0,0 +1,54 @@
+/**
+ * MCP capabilities tool module
+ */
+
+function getToolDefinition() {
+  return {
+    name: 'bootspring_capabilities',
+    description: 'Return capability manifest for assistant clients (tools, premium access, workflow packs, telemetry events).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        mode: {
+          type: 'string',
+          enum: ['local', 'server'],
+          description: 'Optional access mode override'
+        },
+        tier: {
+          type: 'string',
+          description: 'Optional tier override: free, pro, team, enterprise'
+        },
+        entitled: {
+          type: 'boolean',
+          description: 'Optional entitlement override'
+        },
+        client: {
+          type: 'string',
+          description: 'Optional client label (e.g., claude-code, codex)'
+        }
+      },
+      required: []
+    }
+  };
+}
+
+function createHandler({ capabilities }) {
+  return async (args) => {
+    const { mode, tier, entitled, client } = args;
+    const manifest = capabilities.buildCapabilities({ mode, tier, entitled });
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          client: client || 'unspecified',
+          ...manifest
+        }, null, 2)
+      }]
+    };
+  };
+}
+
+module.exports = {
+  getToolDefinition,
+  createHandler
+};

package/mcp/tools/context-tool.js

@@ -0,0 +1,49 @@
+/**
+ * MCP context tool module
+ */
+
+function getToolDefinition() {
+  return {
+    name: 'bootspring_context',
+    description: 'Show or validate the current project context. Use "show" to see project summary, "validate" to check project health.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['show', 'validate', 'summary'],
+          description: 'Action to perform: show (default), validate, or summary'
+        }
+      },
+      required: []
+    }
+  };
+}
+
+function createHandler({ config, context, format }) {
+  return async (args) => {
+    const action = args.action || 'show';
+    const cfg = config.load();
+
+    switch (action) {
+      case 'show':
+      case 'summary': {
+        const ctx = context.get({ config: cfg });
+        return format.contextSummary(ctx);
+      }
+      case 'validate': {
+        const validation = context.validate({ config: cfg });
+        return format.contextValidation(validation);
+      }
+      default:
+        return format.error(`Unknown action: ${action}`, [
+          'Valid actions: show, summary, validate'
+        ]);
+    }
+  };
+}
+
+module.exports = {
+  getToolDefinition,
+  createHandler
+};

package/mcp/tools/dashboard-tool.js

@@ -0,0 +1,58 @@
+/**
+ * MCP dashboard tool module
+ */
+
+function getToolDefinition() {
+  return {
+    name: 'bootspring_dashboard',
+    description: 'Get dashboard status or start URL.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['status', 'url'],
+          description: 'Action: status or url'
+        }
+      },
+      required: []
+    }
+  };
+}
+
+function createHandler({ config }) {
+  return async (args) => {
+    const action = args.action || 'status';
+    const cfg = config.load();
+    const port = cfg.dashboard?.port || 3456;
+
+    switch (action) {
+      case 'status':
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              status: 'available',
+              port,
+              url: `http://localhost:${port}`,
+              command: 'bootspring dashboard'
+            }, null, 2)
+          }]
+        };
+      case 'url':
+        return {
+          content: [{
+            type: 'text',
+            text: `http://localhost:${port}`
+          }]
+        };
+      default:
+        throw new Error(`Unknown action: ${action}`);
+    }
+  };
+}
+
+module.exports = {
+  getToolDefinition,
+  createHandler
+};

package/mcp/tools/generate-tool.js

@@ -0,0 +1,46 @@
+/**
+ * MCP generate tool module
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+function getToolDefinition() {
+  return {
+    name: 'bootspring_generate',
+    description: 'Regenerate the CLAUDE.md context file with current project state.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        full: {
+          type: 'boolean',
+          description: 'Full regeneration including .mcp.json and todo.md'
+        }
+      },
+      required: []
+    }
+  };
+}
+
+function createHandler({ config, context, generateModule }) {
+  return async (_args) => {
+    const cfg = config.load();
+    const ctx = context.get({ config: cfg });
+    const claudePath = path.join(cfg._projectRoot, cfg.paths?.context || 'CLAUDE.md');
+
+    const content = generateModule.generateClaudeMd(cfg, ctx);
+    fs.writeFileSync(claudePath, content);
+
+    return {
+      content: [{
+        type: 'text',
+        text: `Generated CLAUDE.md at ${claudePath}`
+      }]
+    };
+  };
+}
+
+module.exports = {
+  getToolDefinition,
+  createHandler
+};

package/mcp/tools/loop-tool.js

@@ -0,0 +1,134 @@
+/**
+ * MCP loop tool module
+ */
+
+const path = require('path');
+
+function getToolDefinition() {
+  return {
+    name: 'bootspring_loop',
+    description: 'Autonomous task loop management. Create PRDs, check status, manage iterative task execution.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['status', 'next', 'complete', 'create', 'progress'],
+          description: 'Action: status (PRD overview), next (get next story), complete (mark done), create (new PRD), progress (summary)'
+        },
+        name: {
+          type: 'string',
+          description: 'PRD or story name (for create/complete actions)'
+        },
+        storyId: {
+          type: 'string',
+          description: 'Story ID to mark complete'
+        },
+        prdPath: {
+          type: 'string',
+          description: 'Path to prd.json (default: tasks/prd.json)'
+        }
+      },
+      required: ['action']
+    }
+  };
+}
+
+function createHandler({ prdModule, format }) {
+  return async (args) => {
+    const { action, name, storyId, prdPath } = args;
+    const filePath = prdPath || path.join(prdModule.DEFAULT_PRD_DIR, prdModule.DEFAULT_PRD_FILE);
+
+    switch (action) {
+      case 'status':
+      case 'progress': {
+        const prd = prdModule.loadPRD(filePath);
+        if (!prd) {
+          return format.success({
+            summary: 'No PRD found',
+            data: { exists: false },
+            hints: [
+              'Create a PRD with action=create name="feature-name"',
+              'PRDs help you track iterative development progress'
+            ]
+          });
+        }
+        const progress = prdModule.getProgress(prd);
+        return format.loopStatus(prd, progress);
+      }
+
+      case 'next': {
+        const prd = prdModule.loadPRD(filePath);
+        if (!prd) {
+          return format.error('No PRD found', [
+            'Create a PRD first with action=create'
+          ]);
+        }
+        const next = prdModule.getNextStory(prd);
+        if (!next) {
+          return format.success({
+            summary: 'All stories complete! 🎉',
+            data: { complete: true },
+            hints: ['Create a new PRD for your next feature']
+          });
+        }
+        return format.success({
+          summary: `Next Story: ${next.title}`,
+          data: next,
+          hints: [
+            `Mark complete with action=complete storyId="${next.id}"`
+          ]
+        });
+      }
+
+      case 'complete': {
+        if (!storyId) throw new Error('storyId required');
+        const prd = prdModule.loadPRD(filePath);
+        if (!prd) throw new Error('No PRD found');
+
+        prdModule.updateStoryStatus(prd, storyId, 'complete');
+        prdModule.savePRD(prd, filePath);
+
+        const progress = prdModule.getProgress(prd);
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              completed: storyId,
+              progress,
+              allComplete: prdModule.isComplete(prd)
+            }, null, 2)
+          }]
+        };
+      }
+
+      case 'create': {
+        const prdName = name || 'new-feature';
+        const newPrd = prdModule.createPRD(prdName, 'Created via MCP', [
+          { title: 'Setup', description: 'Initial setup' },
+          { title: 'Implementation', description: 'Core implementation' },
+          { title: 'Testing', description: 'Add tests' }
+        ]);
+        const savedPath = prdModule.savePRD(newPrd, filePath);
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              created: savedPath,
+              stories: newPrd.stories.length,
+              message: 'Edit the PRD to define your stories'
+            }, null, 2)
+          }]
+        };
+      }
+
+      default:
+        throw new Error(`Unknown action: ${action}`);
+    }
+  };
+}
+
+module.exports = {
+  getToolDefinition,
+  createHandler
+};