# Bindly MCP Tools Guide

## Before You Start
You need an MCP connection to mcp.bind.ly. Your user should have connected Bindly in their MCP client settings (Claude Desktop, Cursor, etc.).

## Common Workflows

### Save knowledge from a conversation
When a user asks you to save something to Bindly:
1. `mcp_list_spaces()` — find the right Space (usually personal)
2. `mcp_create_binding({ spaceId, title, content, summary, keyPoints })` — save it
3. Confirm to user with the binding name and public URL (if public Space)

### Find previously saved knowledge
When a user asks "what did I save about X?":
1. `mcp_search({ query: "X" })` — returns Tier 1 summaries
2. If the user wants details: `mcp_get_binding({ id, tier: "2" })` — full content
3. If multiple results: present summaries, let user choose

### Update existing knowledge
When a user wants to update a Binding:
1. `mcp_get_binding({ id, tier: "2" })` — get current content
2. `mcp_update_binding({ id, content: newContent, summary: newSummary })` — creates new Version
3. Old versions are preserved — this is immutable

### Build a knowledge collection
When a user wants to organize knowledge:
1. `mcp_create_set({ spaceId, name, description })` — create a Set
2. `mcp_add_version_to_set({ setId, versionId })` — add items
   - `versionId` is a **UUID string**, not the version number. Get it from `mcp_get_binding` (the `versionId` field) or `mcp_list_versions`.
3. `mcp_get_set_context({ setId, maxTokens: 8000 })` — retrieve all at once within token budget

## All Tools (29)

### Binding Tools (7)

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `mcp_get_binding` | Get a Binding (Tier 1/1.5/2) | `id`, `tier` |
| `mcp_get_bindings` | Batch get multiple Bindings | `ids[]`, `tier` |
| `mcp_list_bindings` | List Bindings in a Space | `spaceId`, `limit?` |
| `mcp_create_binding` | Create a Binding | `spaceId`, `title`, `content`, `summary` |
| `mcp_update_binding` | Update (creates new Version) | `id`, `content`, `summary` |
| `mcp_delete_binding` | Delete a Binding | `id` |
| `mcp_search` | Semantic/keyword search | `query`, `spaceId?`, `limit?` |

### Version Tools (2)

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `mcp_list_versions` | List all Versions of a Binding | `bindingId` |
| `mcp_get_version` | Get a specific Version | `bindingId`, `version`, `tier?` |

### Set Tools (7)

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `mcp_list_sets` | List Sets in a Space | `spaceId` |
| `mcp_get_set` | Get Set details | `setId` |
| `mcp_get_set_context` | Get Set content within token budget | `setId`, `maxTokens?` |
| `mcp_create_set` | Create a Set | `spaceId`, `name` |
| `mcp_add_version_to_set` | Add a Version to a Set | `setId`, `versionId` |
| `mcp_remove_version_from_set` | Remove from Set | `setId`, `versionId` |
| `mcp_delete_set` | Delete a Set | `setId` |

### Space Tools (2)

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `mcp_list_spaces` | List accessible Spaces | (none) |
| `mcp_create_space` | Create a Team Space | `name`, `type` |

### Share Tools (3)

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `mcp_create_share` | Create temporary share link | `targetType`, `targetId`, `expiresIn?` |
| `mcp_list_shares` | List share links | `targetType?`, `targetId?` |
| `mcp_delete_share` | Delete a share link | `shareId` |

### Comment Tools (3)

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `mcp_add_comment` | Add a comment | `targetType`, `targetId`, `content` |
| `mcp_list_comments` | List comments | `targetType`, `targetId` |
| `mcp_delete_comment` | Delete own comment | `commentId` |

### Utility Tools (5)

| Tool | Description |
|------|-------------|
| `mcp_recent_activity` | View recent activity |
| `mcp_help` | Get help on any topic |
| `check_connection` | Check MCP connection status |
| `connect` | **Log in to Bindly.** Call this to start OAuth and unlock all 29 tools |
| `disconnect` | Disconnect from Bindly |

## Token Budget Tips
- Use **Tier 1** (~300 tokens) for browsing and exploration
- Use **Tier 1.5** (~800 tokens) when you need a preview to decide
- Use **Tier 2** (full) only when the user needs the complete content
- Use `mcp_get_set_context` with `maxTokens` to stay within context limits

## Error Handling
If you get an error, the response includes a hint. Common patterns:
- "Space not found" — call `mcp_list_spaces()` first
- "Binding not found" — call `mcp_search()` to find correct ID
- "Permission denied" — the user may not have access to that Space