start_capstone_build

Instructions

Implementation Reference

• src/tools/start-capstone-build.ts:60-106 (handler)

  The main registration function registerStartCapstoneBuild that registers the 'start_capstone_build' tool with the MCP server. The handler logic handles 4 cases: (1) no theme - show criteria, (2) no active build - create new, (3) active shaping build - update theme, (4) active building build - error.

  export function registerStartCapstoneBuild(server: McpServer, db: Database.Database, userConfig: UserConfig): void {
    server.tool(
      'start_capstone_build',
      'Start or refine a guided capstone build. Build your own project while learning all 30 certification task statements hands-on.',
      {
        theme: z.string().optional().describe("Your project idea or theme. Omit to see the 30 criteria first."),
      },
      async ({ theme }) => {
        const userId = userConfig.userId;
        ensureUser(db, userId);
  
        // Case 1: No theme — return criteria with instructions
        if (!theme) {
          return {
            content: [{ type: 'text' as const, text: buildResponse(null) }],
          };
        }
  
        const activeBuild = getActiveBuild(db, userId);
  
        // Case 4: Active build in 'building' status — error
        if (activeBuild && activeBuild.status === 'building') {
          return {
            content: [{
              type: 'text' as const,
              text: "You have an active build in progress. Use capstone_build_step with action 'abandon' to start over.",
            }],
            isError: true,
          };
        }
  
        // Case 3: Active build in 'shaping' status — update theme
        if (activeBuild && activeBuild.status === 'shaping') {
          updateBuildTheme(db, activeBuild.id, theme);
          return {
            content: [{ type: 'text' as const, text: buildResponse(theme) }],
          };
        }
  
        // Case 2: No active build — create new build
        createBuild(db, userId, theme);
        return {
          content: [{ type: 'text' as const, text: buildResponse(theme) }],
        };
      }
    );
  }

• src/tools/start-capstone-build.ts:61-66 (schema)

  Tool registration with name 'start_capstone_build', description, and Zod schema for the optional 'theme' parameter.

  server.tool(
    'start_capstone_build',
    'Start or refine a guided capstone build. Build your own project while learning all 30 certification task statements hands-on.',
    {
      theme: z.string().optional().describe("Your project idea or theme. Omit to see the 30 criteria first."),
    },

• src/tools/index.ts:38-42 (registration)

  Registration call where registerStartCapstoneBuild is invoked with the server, db, and userConfig during tool setup.

    registerStartCapstoneBuild(server, db, userConfig);
    registerCapstoneBuildStep(server, db, userConfig);
    registerCapstoneBuildStatus(server, db, userConfig);
    registerDashboard(server, db, userConfig);
  }

• src/tools/start-capstone-build.ts:9-23 (helper)

  Helper function formatCriteria() that formats the 30 architectural criteria across multiple domains into a readable string.

  function formatCriteria(): string {
    const lines: string[] = [];
    let currentDomain = 0;
  
    for (const criterion of CRITERIA) {
      if (criterion.domain !== currentDomain) {
        currentDomain = criterion.domain;
        if (lines.length > 0) lines.push('');
        lines.push(`Domain ${criterion.domain}: ${criterion.domainName}`);
      }
      lines.push(`  ${criterion.id} — ${criterion.title}: ${criterion.description}`);
    }
  
    return lines.join('\n');
  }

• src/tools/start-capstone-build.ts:25-58 (helper)

  Helper function buildResponse() that builds the full response text including criteria, optional theme, and instructions.

  function buildResponse(theme: string | null): string {
    const sections: string[] = [
      '=== GUIDED CAPSTONE BUILD ===',
      '',
      '--- 30 Architectural Criteria ---',
      '',
      formatCriteria(),
    ];
  
    if (theme) {
      sections.push(
        '',
        '--- Your Project Theme ---',
        theme,
        '',
        '--- Instructions ---',
        "Review the criteria above against your project idea. Claude will analyze",
        "which criteria are naturally covered and suggest modifications for any gaps.",
        "When you're satisfied with coverage, use capstone_build_step with action",
        "'confirm' to begin building.",
      );
    } else {
      sections.push(
        '',
        '--- Instructions ---',
        'Choose a project theme that excites you. The best capstone projects are ones',
        'you actually want to build. Provide your theme using start_capstone_build',
        "with a 'theme' parameter, and Claude will analyze how well it covers the",
        '30 criteria above.',
      );
    }
  
    return sections.join('\n');
  }