IdeasBox for LLMs
================

Canonical MCP instructions:
https://api.ideasbox.live/mcp/instructions

MCP endpoint:
https://api.ideasbox.live/mcp

Purpose
-------
IdeasBox is a personal workspace for three content types:
- inspiration: rough thoughts and unfinished fragments
- idea: finished structured content
- resource: reference material, research, links, and supporting notes

Authentication
--------------
IdeasBox MCP supports bearer-token authentication in two ways:
1. Standard user session tokens
2. API keys created in IdeasBox Settings

For non-interactive clients, prefer an API key via:
IDEASBOX_API_KEY

Client setup
------------
If using the IdeasBox MCP package, add it with:
claude mcp add --scope user ideasbox -- npx -y @ideasbox/mcp

The packaged MCP client supports:
- device approval in the browser
- direct API-key auth with IDEASBOX_API_KEY

Behavior rules
--------------
- Call read_before_use first.
- Before creating new content, check for existing related items.
- Use search_items for full-text lookup before creating duplicates.
- Use batch_move_items when several existing items need to change type together.
- Use create_inspiration for rough or exploratory content.
- Use create_idea only for content that is already finished.
- Use create_resource for references or supporting material.
- Do not store reference dumps as ideas.
- Do not silently convert rough notes into ideas.
- Keep content in Markdown.
- Do not change read status unless the user asks.
- Deletion is permanent and should be confirmed.

Todo rules
----------
- Todos belong to a specific item.
- Use todo tools for actionable tasks instead of Markdown checklists.
- Todo changes are reflected in the UI and can update live.

Pagination
----------
- Collection-returning tools are paginated.
- Use page and page_size on list and search tools.
- Paginated responses return:
  - items
  - pagination.page
  - pagination.page_size
  - pagination.total
  - pagination.total_pages
  - pagination.has_next_page
  - pagination.has_prev_page

Primary tools
-------------
- read_before_use
- list_ideas
- list_inspiration
- list_resources
- search_items
- batch_move_items
- get_idea
- create_idea
- create_inspiration
- create_resource
- update_idea
- delete_idea
- promote_inspiration
- list_todos
- create_todo
- update_todo
- delete_todo
- get_settings
- update_settings

Recommended flow
----------------
1. Call read_before_use.
2. Use search_items or the relevant list tool with pagination to avoid duplicates.
3. Fetch the specific item before editing it.
4. Create or update the correct type.
5. Use todo tools for actionable follow-up work.

If you only need the authoritative instruction text, use:
https://api.ideasbox.live/mcp/instructions