Ideas MCP Tools

Three tools expose the ideas domain to MCP clients (Claude Code, Claude Desktop): list_ideas, create_idea, and update_idea. Implementation: services/mcp/src/lkwiz_mcp/tools/ideas.py.

⚠️

This is a partial surface with real behavioral differences from the REST API — not just a thinner one. There is no AI title generation on create, no status-transition validation on update, and no idea deletion or source_url/status-filter parity. See Deviations from REST before you build automation on top of these tools.

`list_ideas`

list_ideas(workspace_id: str, status: str = "") -> str

Lists every idea under workspace_id (a full scan of that workspace's idea partition), then filters in-memory by exact status match if status is non-empty. Requires the caller to be a member of workspace_id.

Returns (JSON-encoded string):

{
  "ideas": [
    {
      "idea_id": "3f9e...",
      "workspace_id": "ws_123",
      "title": "Fixing Onboarding Drop-off",
      "description": "Just realized our onboarding flow loses 40% of users...",
      "status": "new",
      "tags": ["growth"],
      "created_at": "2026-07-17T12:00:00+00:00",
      "updated_at": "2026-07-17T12:00:00+00:00"
    }
  ]
}

This shape omits source_url, created_by, and linked_post_id — fields the REST GET /api/ideas response includes. If you need those, use the REST API.

Does not emit a metric.

`create_idea`

create_idea(workspace_id: str, title: str, description: str = "", tags: list[str] | None = None) -> str

Creates an idea with status: "new". Requires the caller to be a member of workspace_id.

⚠️

Unlike POST /api/ideas, title is stored literally — there is no Bedrock title-generation step here. If you want an AI-generated title, either generate it yourself before calling this tool, or use the REST endpoint instead. See AI title generation for how the REST behavior differs.

Returns:

{
  "idea_id": "3f9e...",
  "workspace_id": "ws_123",
  "title": "Fixing Onboarding Drop-off",
  "status": "new",
  "created_at": "2026-07-17T12:00:00+00:00"
}

Note this response is narrower than the stored item and narrower than the REST create response — it doesn't echo back description, tags, or source_url.

Emits the McpToolInvocation metric (tool_name="create_idea") on success — the only one of these three tools that records a metric.

`update_idea`

update_idea(idea_id: str, workspace_id: str, status: str = "", tags: list[str] | None = None) -> str

Updates an existing idea's status and/or tags. Requires the caller to be a member of workspace_id.

⚠️

status is not validated. PUT /api/ideas/{id}/status only allows new → converted; this tool will write any non-empty string you pass — including values that don't correspond to a real status — straight into the item. There is also no existence check before the write: if idea_id doesn't exist, DynamoDB's UpdateItem creates a new, partial item rather than returning a 404-equivalent error.

Only status and tags can be changed through this tool — title and description cannot.
tags follows a None-vs-[] distinction: omit the parameter (or don't pass it) to leave tags untouched; pass an explicit empty list to clear them.

Returns:

{
  "idea_id": "3f9e...",
  "workspace_id": "ws_123",
  "status": "converted",
  "updated_at": "2026-07-17T12:05:00+00:00"
}

Does not emit a metric.

Deviations from REST

The MCP tools talk to DynamoDB directly with the raw boto3 client (not the common.db / ideas_service layer the REST API uses) and are implemented independently of it. If you're building automation that mixes both surfaces, be aware of:

	REST API	MCP tools
Title on create	AI-generated from your text via Bedrock	Stored literally, as given
Status values on update	Validated (`new`/`converted` only)	Not validated — any string is accepted
Status transition rule	Only `new → converted` enforced (`409` otherwise)	Not enforced at all
Idea existence check on update	Yes (`404` if missing)	No — a missing idea gets silently (partially) created
Delete	`DELETE /api/ideas/{id}`	Not available via MCP
List query strategy	GSI1 query, status pushed into the sort-key prefix	Full partition scan, status filtered in-memory
Fields returned	Full idea record	Narrower subset (see each tool above)
Metrics on create	`IdeaCaptured`	`McpToolInvocation` only

In practice: use these tools for quick idea capture and status nudges from an AI client, but drive anything that depends on status-transition correctness, deletion, or a complete record shape through the REST API.

Ideas MCP Tools

list_ideas

create_idea

update_idea

Deviations from REST

See also

`list_ideas`

`create_idea`

`update_idea`