trak_flow 0.1.3

data/docs/mcp/resources.md

@@ -0,0 +1,284 @@
+# MCP Resources Reference
+
+Resources provide read-only access to TrakFlow data. AI agents can use resources to understand the current state of tasks without modifying anything.
+
+## Available Resources
+
+### Task List
+
+**URI:** `trak_flow://tasks`
+**Name:** Task List
+**Description:** All tasks in the project
+
+#### Content
+
+```json
+{
+  "tasks": [
+    {
+      "id": "tf-abc123",
+      "title": "Implement authentication",
+      "status": "in_progress",
+      "priority": 1,
+      "type": "feature",
+      "assignee": "claude",
+      "created_at": "2024-01-15T10:00:00Z"
+    },
+    {
+      "id": "tf-def456",
+      "title": "Fix login bug",
+      "status": "open",
+      "priority": 0,
+      "type": "bug"
+    }
+  ],
+  "summary": {
+    "total": 42,
+    "by_status": {
+      "open": 15,
+      "in_progress": 5,
+      "blocked": 3,
+      "closed": 19
+    }
+  }
+}
+```
+
+### Ready Tasks
+
+**URI:** `trak_flow://ready`
+**Name:** Ready Tasks
+**Description:** Tasks with no open blockers, ready to work on
+
+#### Content
+
+```json
+{
+  "tasks": [
+    {
+      "id": "tf-abc123",
+      "title": "Implement feature X",
+      "priority": 1,
+      "type": "feature"
+    },
+    {
+      "id": "tf-def456",
+      "title": "Fix critical bug",
+      "priority": 0,
+      "type": "bug"
+    }
+  ],
+  "count": 2
+}
+```
+
+### Dependencies
+
+**URI:** `trak_flow://dependencies`
+**Name:** Dependencies
+**Description:** Dependency graph between tasks
+
+#### Content
+
+```json
+{
+  "dependencies": [
+    {
+      "source_id": "tf-design1",
+      "target_id": "tf-implement1",
+      "type": "blocks"
+    },
+    {
+      "source_id": "tf-implement1",
+      "target_id": "tf-test1",
+      "type": "blocks"
+    }
+  ],
+  "summary": {
+    "total": 34,
+    "by_type": {
+      "blocks": 28,
+      "related": 4,
+      "parent-child": 2
+    }
+  }
+}
+```
+
+### Plans
+
+**URI:** `trak_flow://plans`
+**Name:** Plans
+**Description:** Plan blueprints and their Workflows
+
+#### Content
+
+```json
+{
+  "plans": [
+    {
+      "id": "tf-plan1",
+      "title": "Deploy Process",
+      "steps": [
+        {"title": "Run tests"},
+        {"title": "Build artifacts"},
+        {"title": "Deploy to staging"},
+        {"title": "Deploy to production"}
+      ],
+      "workflow_count": 3
+    }
+  ],
+  "active_workflows": [
+    {
+      "id": "tf-wf1",
+      "source_plan_id": "tf-plan1",
+      "title": "Deploy v1.2.0",
+      "progress": {
+        "completed": 2,
+        "total": 4
+      }
+    }
+  ]
+}
+```
+
+### Labels
+
+**URI:** `trak_flow://labels`
+**Name:** Labels
+**Description:** All labels used in the project
+
+#### Content
+
+```json
+{
+  "labels": [
+    {"name": "frontend", "task_count": 12},
+    {"name": "backend", "task_count": 8},
+    {"name": "urgent", "task_count": 3},
+    {"name": "v2.0", "task_count": 15}
+  ]
+}
+```
+
+### Project Summary
+
+**URI:** `trak_flow://summary`
+**Name:** Project Summary
+**Description:** Overview of project status
+
+#### Content
+
+```json
+{
+  "project": {
+    "total_tasks": 47,
+    "open_tasks": 12,
+    "in_progress": 5,
+    "blocked": 3,
+    "closed": 27
+  },
+  "priorities": {
+    "critical": 2,
+    "high": 8,
+    "medium": 25,
+    "low": 10,
+    "backlog": 2
+  },
+  "types": {
+    "task": 30,
+    "bug": 8,
+    "feature": 5,
+    "epic": 3,
+    "chore": 1
+  },
+  "recent_activity": [
+    {
+      "task_id": "tf-abc123",
+      "action": "closed",
+      "timestamp": "2024-01-16T14:30:00Z"
+    },
+    {
+      "task_id": "tf-def456",
+      "action": "started",
+      "timestamp": "2024-01-16T14:00:00Z"
+    }
+  ]
+}
+```
+
+## Accessing Resources
+
+### Using MCP Client
+
+```ruby
+# Get a resource by name
+task_list = client.resource("Task List")
+
+# Access the content
+content = task_list.content
+puts content["tasks"].length
+
+# Or get by URI
+ready = client.resource_by_uri("trak_flow://ready")
+```
+
+### Resource Properties
+
+Each resource has these properties:
+
+| Property | Description |
+|----------|-------------|
+| `uri` | Unique resource identifier |
+| `name` | Human-readable name |
+| `description` | What the resource contains |
+| `mimeType` | Content type (application/json) |
+
+## Resource Updates
+
+Resources are read-only snapshots. To get updated data:
+
+1. Request the resource again
+2. Subscribe to updates via SSE (HTTP transport)
+
+### SSE Updates (HTTP Transport)
+
+When using HTTP/SSE transport, you can subscribe to resource updates:
+
+```ruby
+client.on_resource_update("trak_flow://tasks") do |content|
+  puts "Tasks updated: #{content["tasks"].length} tasks"
+end
+```
+
+## Using Resources with LLMs
+
+Resources are designed to provide context to AI agents. Example prompt:
+
+```
+Based on the current task list, what should I work on next?
+
+Task List:
+{resource: trak_flow://tasks}
+
+Ready Tasks:
+{resource: trak_flow://ready}
+```
+
+The AI can analyze the data and recommend next steps.
+
+## Resource Best Practices
+
+### For AI Agents
+
+1. **Start with summary** - Get the big picture first
+2. **Check ready tasks** - Know what's actionable
+3. **Review dependencies** - Understand blockers
+4. **Cache wisely** - Resources are point-in-time snapshots
+
+### For Integration
+
+1. **Poll sparingly** - Resources don't change constantly
+2. **Use SSE when available** - For real-time updates
+3. **Handle errors gracefully** - Resources may be empty
+4. **Respect rate limits** - Don't overload the server

data/docs/mcp/tools.md

@@ -0,0 +1,457 @@
+# MCP Tools Reference
+
+This page documents all tools exposed by the TrakFlow MCP server.
+
+## Task Management Tools
+
+### task_create
+
+Create a new task.
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `title` | string | Yes | Task title |
+| `description` | string | No | Detailed description |
+| `type` | string | No | Task type (task, bug, feature, epic, chore) |
+| `priority` | integer | No | Priority 0-4 (default: 2) |
+| `assignee` | string | No | Assigned user/agent |
+| `parent_id` | string | No | Parent task ID |
+| `plan` | boolean | No | Create as Plan blueprint |
+
+#### Returns
+
+```json
+{
+  "success": true,
+  "task": {
+    "id": "tf-abc123",
+    "title": "New task",
+    "status": "open",
+    "priority": 2,
+    "type": "task",
+    "created_at": "2024-01-15T10:00:00Z"
+  }
+}
+```
+
+#### Example
+
+```ruby
+tool = client.tool("task_create")
+result = tool.execute(
+  title: "Implement user authentication",
+  type: "feature",
+  priority: 1,
+  description: "Add login, logout, and session management"
+)
+```
+
+### task_list
+
+List tasks with optional filters.
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `status` | string | No | Filter by status |
+| `type` | string | No | Filter by type |
+| `priority` | integer | No | Filter by priority |
+| `assignee` | string | No | Filter by assignee |
+| `label` | string | No | Filter by label |
+| `parent_id` | string | No | Filter by parent |
+| `limit` | integer | No | Max results |
+| `offset` | integer | No | Skip results |
+
+#### Returns
+
+```json
+{
+  "tasks": [
+    {"id": "tf-abc123", "title": "Task 1", "status": "open", "priority": 2},
+    {"id": "tf-def456", "title": "Task 2", "status": "in_progress", "priority": 1}
+  ],
+  "count": 2,
+  "total": 42
+}
+```
+
+#### Example
+
+```ruby
+tool = client.tool("task_list")
+result = tool.execute(status: "open", priority: 1)
+```
+
+### task_show
+
+Get detailed information about a task.
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Task ID |
+| `include_deps` | boolean | No | Include dependencies |
+| `include_labels` | boolean | No | Include labels |
+
+#### Returns
+
+```json
+{
+  "task": {
+    "id": "tf-abc123",
+    "title": "Implement feature",
+    "description": "Detailed description",
+    "status": "in_progress",
+    "priority": 1,
+    "type": "feature",
+    "assignee": "claude",
+    "created_at": "2024-01-15T10:00:00Z",
+    "updated_at": "2024-01-16T14:30:00Z",
+    "notes": "..."
+  },
+  "dependencies": {
+    "blocked_by": ["tf-design1"],
+    "blocks": ["tf-test1", "tf-docs1"]
+  },
+  "labels": ["backend", "security"]
+}
+```
+
+### task_update
+
+Update task properties.
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Task ID |
+| `title` | string | No | New title |
+| `description` | string | No | New description |
+| `priority` | integer | No | New priority |
+| `type` | string | No | New type |
+| `assignee` | string | No | New assignee |
+| `notes` | string | No | Append to notes |
+
+#### Returns
+
+```json
+{
+  "success": true,
+  "task": {
+    "id": "tf-abc123",
+    "title": "Updated title",
+    "updated_at": "2024-01-16T15:00:00Z"
+  }
+}
+```
+
+### task_start
+
+Mark a task as in progress.
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Task ID |
+
+#### Returns
+
+```json
+{
+  "success": true,
+  "task": {
+    "id": "tf-abc123",
+    "status": "in_progress"
+  }
+}
+```
+
+### task_close
+
+Complete a task.
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Task ID |
+| `summary` | string | No | Completion summary |
+
+#### Returns
+
+```json
+{
+  "success": true,
+  "task": {
+    "id": "tf-abc123",
+    "status": "closed",
+    "closed_at": "2024-01-16T16:00:00Z"
+  }
+}
+```
+
+### task_block
+
+Mark a task as blocked.
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Task ID |
+| `reason` | string | No | Blocking reason |
+
+#### Returns
+
+```json
+{
+  "success": true,
+  "task": {
+    "id": "tf-abc123",
+    "status": "blocked"
+  }
+}
+```
+
+### task_reopen
+
+Reopen a closed or deferred task.
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Task ID |
+
+#### Returns
+
+```json
+{
+  "success": true,
+  "task": {
+    "id": "tf-abc123",
+    "status": "open"
+  }
+}
+```
+
+## Plan & Workflow Tools
+
+### plan_create
+
+Create a Plan blueprint.
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `title` | string | Yes | Plan title |
+| `description` | string | No | Plan description |
+
+#### Returns
+
+```json
+{
+  "success": true,
+  "plan": {
+    "id": "tf-plan123",
+    "title": "Deploy Process",
+    "plan": true
+  }
+}
+```
+
+### plan_add_step
+
+Add a step to a Plan.
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `plan_id` | string | Yes | Plan ID |
+| `title` | string | Yes | Step title |
+| `description` | string | No | Step description |
+
+### plan_start
+
+Create a persistent Workflow from a Plan.
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `plan_id` | string | Yes | Plan ID |
+| `title` | string | No | Custom Workflow title |
+
+#### Returns
+
+```json
+{
+  "success": true,
+  "workflow": {
+    "id": "tf-wf123",
+    "source_plan_id": "tf-plan123",
+    "ephemeral": false,
+    "tasks": [
+      {"id": "tf-task1", "title": "Step 1"},
+      {"id": "tf-task2", "title": "Step 2"}
+    ]
+  }
+}
+```
+
+### plan_execute
+
+Create an ephemeral Workflow from a Plan.
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `plan_id` | string | Yes | Plan ID |
+| `title` | string | No | Custom Workflow title |
+
+## Dependency Tools
+
+### dep_add
+
+Add a dependency between tasks.
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `source_id` | string | Yes | Source task ID |
+| `target_id` | string | Yes | Target task ID |
+| `type` | string | No | Dependency type (blocks, related) |
+
+#### Returns
+
+```json
+{
+  "success": true,
+  "dependency": {
+    "source_id": "tf-abc123",
+    "target_id": "tf-def456",
+    "type": "blocks"
+  }
+}
+```
+
+### dep_remove
+
+Remove a dependency.
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `source_id` | string | Yes | Source task ID |
+| `target_id` | string | Yes | Target task ID |
+
+### ready_tasks
+
+Find tasks with no open blockers.
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `type` | string | No | Filter by type |
+| `priority` | integer | No | Filter by priority |
+| `limit` | integer | No | Max results |
+
+#### Returns
+
+```json
+{
+  "tasks": [
+    {"id": "tf-abc123", "title": "Ready task 1"},
+    {"id": "tf-def456", "title": "Ready task 2"}
+  ],
+  "count": 2
+}
+```
+
+## Label Tools
+
+### label_add
+
+Add a label to a task.
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task_id` | string | Yes | Task ID |
+| `label` | string | Yes | Label name |
+
+#### Returns
+
+```json
+{
+  "success": true,
+  "task_id": "tf-abc123",
+  "label": "frontend"
+}
+```
+
+### label_remove
+
+Remove a label from a task.
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task_id` | string | Yes | Task ID |
+| `label` | string | Yes | Label name |
+
+### label_list
+
+List labels on a task.
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task_id` | string | Yes | Task ID |
+
+#### Returns
+
+```json
+{
+  "task_id": "tf-abc123",
+  "labels": ["frontend", "urgent", "v2.0"]
+}
+```
+
+## Error Handling
+
+All tools return errors in a consistent format:
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "not_found",
+    "message": "Task not found: tf-invalid"
+  }
+}
+```
+
+### Error Codes
+
+| Code | Description |
+|------|-------------|
+| `not_found` | Resource not found |
+| `validation_error` | Invalid parameters |
+| `conflict` | Conflicting operation |
+| `internal_error` | Server error |