feat: add create_idea MCP tool for draft task creation

[simple-agent-manager]

Summary

• Adds create_idea MCP tool that lets agents capture ideas as draft tasks without spinning up a TaskRunner DO or provisioning a workspace
• Auto-links created ideas to the current chat session for traceability
• Configurable title/description max lengths via MCP_IDEA_TITLE_MAX_LENGTH and MCP_IDEA_DESCRIPTION_MAX_LENGTH env vars

Validation

• pnpm lint
• pnpm typecheck
• pnpm test

Staging Verification (REQUIRED for all code changes — merge-blocking)

• Staging deployment green — Deploy Staging workflow triggered manually and passed for this branch (run 23308216719)
• Live app verified via Playwright — logged into app.sammy.party (staging) using test credentials and actively tested the application
• Existing workflows confirmed working — navigated dashboard, projects, and settings; confirmed no regressions in core flows (pages load, data displays, navigation works, no new console errors)
• New feature/fix verified on staging — MCP tool is backend-only, callable by agents via MCP protocol; verified API health + app loads correctly after deployment
• Infrastructure verification completed — N/A: no infra changes
• Mobile and desktop verification notes added for UI changes — N/A: no UI changes

Staging Verification Evidence

Deployed to staging and verified via Playwright:

• App loads at app.sammy.party, dashboard renders with project cards
• Settings page loads with cloud provider configuration
• API health endpoint returns {"status":"healthy"} with all bindings present
• No console errors observed during navigation
• Feature is a backend MCP tool — agents call it via JSON-RPC, not directly testable via browser UI

End-to-End Verification (Required for multi-component changes)

• Data flow traced from user input to final outcome with code path citations
• Capability test exercises the complete happy path across system boundaries
• All spec/doc assumptions about existing behavior verified against code
• N/A: single-component change (MCP route handler only)

Data Flow Trace

1. Agent calls create_idea MCP tool via JSON-RPC
   → apps/api/src/routes/mcp.ts route handler dispatches to handleCreateIdea()
2. Handler validates input, generates ULID, inserts draft task
   → handleCreateIdea() → env.DATABASE.prepare("INSERT INTO tasks...") with status='draft'
3. Handler auto-links to chat session (best-effort)
   → resolveSessionId() → projectDataService.linkSessionIdea()
4. Returns task ID, title, status, linked flag to agent

Untested Gaps

N/A: full flow covered by automated tests (7 unit tests in mcp.test.ts covering validation, insertion, auto-linking, and no-DO-spawn)

Post-Mortem (Required for bug fix PRs)

N/A: not a bug fix

Exceptions (If any)

• Scope: N/A
• Rationale: N/A
• Expiration: N/A

Agent Preflight (Required)

• Preflight completed before code changes

Classification

• external-api-change
• cross-component-change
• business-logic-change
• public-surface-change
• docs-sync-change
• security-sensitive-change
• ui-change
• infra-change

External References

N/A: Internal MCP tool implementation using existing patterns — no external APIs consumed. Followed existing dispatch_task and link_idea tool patterns in apps/api/src/routes/mcp.ts.

Codebase Impact Analysis

• apps/api/src/index.ts — Added 2 env var declarations (MCP_IDEA_TITLE_MAX_LENGTH, MCP_IDEA_DESCRIPTION_MAX_LENGTH) to Env interface
• apps/api/src/routes/mcp.ts — New create_idea tool definition in MCP_TOOLS array, new handleCreateIdea() handler function, new case in tool dispatch switch
• apps/api/tests/unit/routes/mcp.test.ts — 7 new tests for the create_idea tool
• No changes to shared types, providers, web UI, or VM agent

Documentation & Specs

N/A: Backend MCP tool addition — no user-facing documentation changes needed. The tool is self-documenting via its MCP tool description visible to agents.

Constitution & Risk Check

• Principle XI (No Hardcoded Values): All limits configurable via env vars — MCP_IDEA_TITLE_MAX_LENGTH (default: 200), MCP_IDEA_DESCRIPTION_MAX_LENGTH (default: 32000)
• Principle XIII (Fail-Fast): Input validation rejects empty/missing title and description with proper JSON-RPC error codes
• No new security surfaces — reuses existing MCP token authentication and sanitizeUserInput() for XSS prevention

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate failed

Failed conditions
7.9% Duplication on New Code (required ≤ 3%)

See analysis details on SonarQube Cloud