@claudetools/tools 0.3.9 → 0.5.0

package/dist/tools.js

@@ -668,6 +668,128 @@ export function registerToolDefinitions(server) {
                     properties: {},
                 },
             },
+            {
+                name: 'task_epic_status',
+                description: 'Get epic progress status with task counts by status. Auto-completes epic when all child tasks are done. Use this to track epic progress and see completion percentage.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        epic_id: {
+                            type: 'string',
+                            description: 'The epic ID to get status for',
+                        },
+                    },
+                    required: ['epic_id'],
+                },
+            },
+            {
+                name: 'task_detect_timeouts',
+                description: 'Detect tasks that have timed out (lock expired while in_progress). These are likely abandoned or failed tasks that need attention.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        project_id: {
+                            type: 'string',
+                            description: 'Project ID (optional, uses default if not provided)',
+                        },
+                    },
+                },
+            },
+            {
+                name: 'task_retry',
+                description: 'Retry a failed or timed-out task. Resets task to ready status if under retry limit, or marks as failed permanently if limit exceeded.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        task_id: {
+                            type: 'string',
+                            description: 'The task ID to retry',
+                        },
+                        max_retries: {
+                            type: 'number',
+                            description: 'Maximum number of retries allowed (default: 3)',
+                        },
+                        error_context: {
+                            type: 'string',
+                            description: 'Description of the error or failure reason',
+                        },
+                        project_id: {
+                            type: 'string',
+                            description: 'Project ID (optional, uses default if not provided)',
+                        },
+                    },
+                    required: ['task_id'],
+                },
+            },
+            {
+                name: 'task_fail',
+                description: 'Explicitly mark a task as failed with error context. Use when a task cannot be completed.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        task_id: {
+                            type: 'string',
+                            description: 'The task ID to mark as failed',
+                        },
+                        error_context: {
+                            type: 'string',
+                            description: 'Description of why the task failed',
+                        },
+                        agent_id: {
+                            type: 'string',
+                            description: 'Agent ID (optional, defaults to "claude-code")',
+                        },
+                        project_id: {
+                            type: 'string',
+                            description: 'Project ID (optional, uses default if not provided)',
+                        },
+                    },
+                    required: ['task_id', 'error_context'],
+                },
+            },
+            {
+                name: 'task_auto_retry_timeouts',
+                description: 'Automatically detect and retry all timed-out tasks. Tasks under retry limit are reset to ready, those exceeding limit are marked as failed.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        max_retries: {
+                            type: 'number',
+                            description: 'Maximum number of retries per task (default: 3)',
+                        },
+                        project_id: {
+                            type: 'string',
+                            description: 'Project ID (optional, uses default if not provided)',
+                        },
+                    },
+                },
+            },
+            {
+                name: 'task_orchestrate',
+                description: 'Orchestrate autonomous multi-agent execution for an epic. Dispatches parallel workers, monitors progress, handles failures, and continues until completion.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        epic_id: {
+                            type: 'string',
+                            description: 'Epic ID to orchestrate',
+                        },
+                        max_parallel: {
+                            type: 'number',
+                            description: 'Max parallel tasks (default: 5)',
+                        },
+                        max_retries: {
+                            type: 'number',
+                            description: 'Max retries per task (default: 3)',
+                        },
+                        dry_run: {
+                            type: 'boolean',
+                            description: 'Preview without executing (default: false)',
+                        },
+                    },
+                    required: ['epic_id'],
+                },
+            },
             // =========================================================================
             // CODEBASE MAPPING TOOLS
             // =========================================================================
@@ -743,6 +865,198 @@ export function registerToolDefinitions(server) {
                     required: ['function_name'],
                 },
             },
+            // =========================================================================
+            // DOCUMENTATION CACHING TOOLS
+            // =========================================================================
+            {
+                name: 'docs_cache',
+                description: 'Ensure documentation for a library is cached. Automatically fetches from Context7 if not already cached. Use simple library names like "react", "next.js", "zod", "tanstack-query".',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        library: {
+                            type: 'string',
+                            description: 'Library name to cache docs for (e.g., "react", "next.js", "zod", "tanstack-query", "supabase")',
+                        },
+                        topic: {
+                            type: 'string',
+                            description: 'Optional topic to focus on (e.g., "routing", "authentication")',
+                        },
+                    },
+                    required: ['library'],
+                },
+            },
+            {
+                name: 'docs_list',
+                description: 'List all cached documentation libraries (global cache shared across projects).',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+            },
+            {
+                name: 'docs_get',
+                description: 'Get cached documentation for a specific library. Returns the full cached content.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        library: {
+                            type: 'string',
+                            description: 'Library name to get docs for (e.g., "react", "next.js")',
+                        },
+                        topic: {
+                            type: 'string',
+                            description: 'Optional topic to filter docs by',
+                        },
+                    },
+                    required: ['library'],
+                },
+            },
+            // =========================================================================
+            // CODEDNA CODE GENERATION TOOLS
+            // =========================================================================
+            {
+                name: 'codedna_generate_api',
+                description: 'Generate a complete REST API with CRUD operations from an Entity DSL specification. Saves 95-99% tokens vs writing code manually. Example: codedna_generate_api("User(email:string:unique, password:string:hashed)", "express", { auth: true })',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        spec: {
+                            type: 'string',
+                            description: 'Entity DSL specification (e.g., "User(email:string:unique:required, password:string:hashed, age:integer:min(18))")',
+                        },
+                        framework: {
+                            type: 'string',
+                            enum: ['express', 'fastapi', 'nestjs'],
+                            description: 'API framework to use',
+                        },
+                        options: {
+                            type: 'object',
+                            properties: {
+                                auth: {
+                                    type: 'boolean',
+                                    description: 'Include JWT authentication middleware',
+                                },
+                                validation: {
+                                    type: 'boolean',
+                                    description: 'Add input validation',
+                                },
+                                tests: {
+                                    type: 'boolean',
+                                    description: 'Generate test files',
+                                },
+                                database: {
+                                    type: 'string',
+                                    enum: ['postgresql', 'mysql', 'mongodb'],
+                                    description: 'Target database',
+                                },
+                            },
+                        },
+                    },
+                    required: ['spec', 'framework'],
+                },
+            },
+            {
+                name: 'codedna_generate_frontend',
+                description: 'Generate frontend application with forms and tables from Entity DSL. Saves 95-99% tokens vs writing components manually.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        spec: {
+                            type: 'string',
+                            description: 'Entity DSL specification',
+                        },
+                        framework: {
+                            type: 'string',
+                            enum: ['nextjs', 'react', 'vue'],
+                            description: 'Frontend framework to use',
+                        },
+                        options: {
+                            type: 'object',
+                            properties: {
+                                ui: {
+                                    type: 'string',
+                                    enum: ['shadcn', 'mui', 'chakra'],
+                                    description: 'UI component library',
+                                },
+                                forms: {
+                                    type: 'boolean',
+                                    description: 'Generate forms',
+                                },
+                                tables: {
+                                    type: 'boolean',
+                                    description: 'Generate data tables',
+                                },
+                                routing: {
+                                    type: 'boolean',
+                                    description: 'Setup routing',
+                                },
+                            },
+                        },
+                    },
+                    required: ['spec', 'framework'],
+                },
+            },
+            {
+                name: 'codedna_generate_component',
+                description: 'Generate single UI component (form, table, card, modal) from Entity DSL.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        spec: {
+                            type: 'string',
+                            description: 'Entity DSL specification or component spec',
+                        },
+                        type: {
+                            type: 'string',
+                            enum: ['form', 'table', 'card', 'modal'],
+                            description: 'Component type to generate',
+                        },
+                        framework: {
+                            type: 'string',
+                            enum: ['react', 'vue', 'svelte'],
+                            description: 'Frontend framework',
+                        },
+                        options: {
+                            type: 'object',
+                            properties: {
+                                ui: {
+                                    type: 'string',
+                                    enum: ['shadcn', 'mui', 'chakra'],
+                                    description: 'UI library',
+                                },
+                                validation: {
+                                    type: 'boolean',
+                                    description: 'Include validation',
+                                },
+                            },
+                        },
+                    },
+                    required: ['spec', 'type', 'framework'],
+                },
+            },
+            {
+                name: 'codedna_list_generators',
+                description: 'List all available code generators and their capabilities.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+            },
+            {
+                name: 'codedna_validate_spec',
+                description: 'Validate Entity DSL syntax without generating code. Returns parsed structure or errors.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        spec: {
+                            type: 'string',
+                            description: 'Entity DSL specification to validate',
+                        },
+                    },
+                    required: ['spec'],
+                },
+            },
         ],
     }));
 }

package/docs/AUTO-REGISTRATION.md

@@ -0,0 +1,353 @@
+# Auto Project Registration
+
+The ClaudeTools Memory MCP server now supports automatic project registration. When you use the server in a new directory, it will automatically register that directory as a project with the ClaudeTools API and cache the binding locally.
+
+## How It Works
+
+### 1. Project ID Resolution Flow
+
+```
+MCP Server Starts
+    ↓
+Check CLAUDETOOLS_PROJECT_ID env var
+    ↓ (if not set)
+Check ~/.claudetools/projects.json cache
+    ↓ (if no binding found)
+Auto-register via API (if autoRegister: true)
+    ↓
+Cache project_id locally
+    ↓
+Use project_id for all memory operations
+```
+
+### 2. System Registration
+
+On first use, the server registers your machine:
+
+- **System ID**: Unique identifier for this machine (e.g., `sys_abc123...`)
+- **Hostname**: Your machine's hostname
+- **Platform**: Operating system (darwin, linux, win32)
+- **Username**: Current user
+
+The system ID is cached in `~/.claudetools/projects.json`:
+
+```json
+{
+  "system_id": "sys_bdbcff93724e4a05b488",
+  "bindings": [...],
+  "last_sync": "2025-12-03T02:37:44.635Z"
+}
+```
+
+### 3. Project Binding
+
+When you use the MCP server in a directory for the first time:
+
+1. **Detects** project metadata:
+   - Project name (from directory name)
+   - Local path (absolute path)
+   - Git remote (if available)
+
+2. **Registers** via API:
+   - Creates project in your ClaudeTools account
+   - Returns project_id (UUID format: `proj_xxxxxxxxxxxxxxxxxxxx`)
+
+3. **Creates binding** linking:
+   - System ID (your machine)
+   - Project ID (the project)
+   - Local path (where the project lives)
+
+4. **Caches** binding locally in `~/.claudetools/projects.json`:
+
+```json
+{
+  "bindings": [
+    {
+      "binding_id": "bind_904de164763a47d0924e",
+      "project_id": "proj_3a33ce7579874351b990",
+      "system_id": "sys_bdbcff93724e4a05b488",
+      "local_path": "/Users/you/Projects/myproject",
+      "git_remote": "git@github.com:you/myproject.git",
+      "project_name": "myproject",
+      "org_id": "your-org-id",
+      "cached_at": "2025-12-03T02:37:44.635Z"
+    }
+  ],
+  "system_id": "sys_bdbcff93724e4a05b488",
+  "last_sync": "2025-12-03T02:37:44.635Z"
+}
+```
+
+## Configuration
+
+### Enable/Disable Auto-Registration
+
+Edit `~/.claudetools/config.json`:
+
+```json
+{
+  "autoRegister": true,  // Enable auto-registration (default)
+  "apiUrl": "https://api.claudetools.dev",
+  "apiKey": "ct_live_..."
+}
+```
+
+To disable auto-registration:
+
+```json
+{
+  "autoRegister": false
+}
+```
+
+### Set API Key
+
+Three ways to configure your API key:
+
+1. **Environment variable** (highest priority):
+   ```bash
+   export CLAUDETOOLS_API_KEY="ct_live_..."
+   # or
+   export MEMORY_API_KEY="ct_live_..."
+   ```
+
+2. **Config file**:
+   ```json
+   {
+     "apiKey": "ct_live_..."
+   }
+   ```
+
+3. **.env file** (in project root):
+   ```bash
+   MEMORY_API_KEY=ct_live_...
+   ```
+
+### Manual Project ID
+
+If you want to use a specific project ID instead of auto-registering:
+
+```bash
+export CLAUDETOOLS_PROJECT_ID="proj_xxxxxxxxxxxxxxxxxxxx"
+```
+
+## Project ID Format Validation
+
+All project IDs must follow the format:
+- Prefix: `proj_`
+- 20 hexadecimal characters
+- Example: `proj_3a33ce7579874351b990`
+
+Invalid formats will be rejected with a clear error message.
+
+## Cache Management
+
+### View Cache
+
+```bash
+cat ~/.claudetools/projects.json
+```
+
+### Clear Cache
+
+```bash
+rm ~/.claudetools/projects.json
+```
+
+The server will auto-register on next use (if `autoRegister: true`).
+
+### Sync from API
+
+Future feature - will pull all your project bindings from the API:
+
+```typescript
+import { syncProjectsFromAPI } from './helpers/project-registration.js';
+await syncProjectsFromAPI();
+```
+
+## Path Matching
+
+The server uses smart path matching:
+
+1. **Exact match**: `/Users/you/Projects/myproject` matches exactly
+2. **Prefix match**: `/Users/you/Projects/myproject/src` uses parent binding
+3. **Longest match**: If multiple bindings match, uses the longest path
+
+Example:
+```json
+{
+  "bindings": [
+    {"local_path": "/Users/you/Projects"},
+    {"local_path": "/Users/you/Projects/myproject"}
+  ]
+}
+```
+
+Using server from `/Users/you/Projects/myproject/src`:
+- ✅ Uses: `/Users/you/Projects/myproject` (longer match)
+- ❌ Not: `/Users/you/Projects` (shorter match)
+
+## Error Handling
+
+### No API Key
+
+```
+Error: No API key found. Set CLAUDETOOLS_API_KEY or MEMORY_API_KEY in environment,
+or configure via ~/.claudetools/config.json
+```
+
+**Solution**: Set API key using one of the methods above.
+
+### Auto-Registration Disabled
+
+```
+Error: No project binding found for /path/to/project and auto-registration is disabled.
+To register this project:
+  1. Set CLAUDETOOLS_PROJECT_ID environment variable with a valid proj_* UUID
+  2. Enable autoRegister in ~/.claudetools/config.json
+  3. Or manually register via API
+```
+
+**Solution**: Either:
+- Enable auto-registration in config
+- Set `CLAUDETOOLS_PROJECT_ID` manually
+- Register project via ClaudeTools dashboard
+
+### Invalid Project ID Format
+
+```
+Error: Invalid project ID format: my-project-123
+Expected format: proj_xxxxxxxxxxxxxxxxxxxx (20 hex chars)
+```
+
+**Solution**: Use a valid UUID format or let the system auto-register.
+
+### Network Error
+
+```
+Error: Failed to auto-register project: API error: 500 Internal Server Error
+```
+
+**Solution**: Check:
+1. API URL is correct in config
+2. Network connectivity to `api.claudetools.dev`
+3. API service status
+
+## Testing
+
+Run the registration test suite:
+
+```bash
+cd mcp-server
+npm run build
+npx tsx test-registration.ts
+```
+
+Expected output:
+```
+================================================================================
+Testing Auto-Registration System
+================================================================================
+
+Test 1: Direct registration via getOrRegisterProject()
+✅ Success: proj_3a33ce7579874351b990
+
+Test 2: Resolution via resolveProjectIdAsync()
+✅ Success: proj_3a33ce7579874351b990
+
+Test 3: Verify consistency
+✅ Both methods returned same ID: proj_3a33ce7579874351b990
+
+Test 4: Check cache file
+Cache file exists at: /Users/you/.claudetools/projects.json
+Bindings count: 1
+System ID: sys_bdbcff93724e4a05b488
+
+✅ All tests passed!
+================================================================================
+```
+
+## Known Issues
+
+### API Schema Error (Temporary)
+
+Currently, the project creation endpoint has a schema issue:
+```
+Error: table projects has no column named created_by
+```
+
+**Workaround**: Use an existing cached binding or manually set `CLAUDETOOLS_PROJECT_ID`.
+
+This will be fixed in the next API deployment.
+
+## Migration from Name-Based IDs
+
+If you were previously using name-based IDs like `claude-code-myproject`:
+
+1. **Delete old cache**: `rm ~/.claudetools/projects.json`
+2. **Set API key**: Export `CLAUDETOOLS_API_KEY`
+3. **Restart server**: Will auto-register with proper UUID
+
+Or keep using the old ID by setting:
+```bash
+export CLAUDETOOLS_PROJECT_ID="claude-code-myproject"
+```
+
+However, this is **not recommended** as UUID-based IDs provide:
+- ✅ Global uniqueness
+- ✅ Cross-machine project sharing
+- ✅ Proper project management in ClaudeTools dashboard
+- ✅ Multi-system bindings
+
+## Architecture
+
+### Key Files
+
+- `src/helpers/project-registration.ts` - Registration logic
+- `src/helpers/config.ts` - Project ID resolution
+- `src/helpers/config-manager.ts` - Configuration management
+- `~/.claudetools/config.json` - User configuration
+- `~/.claudetools/projects.json` - Cached bindings
+
+### API Endpoints
+
+- `POST /api/v1/systems/register` - Register machine
+- `POST /api/v1/projects` - Create project
+- `POST /api/v1/systems/{system_id}/bindings` - Create binding
+- `GET /api/v1/systems/{system_id}/bindings` - List bindings (future)
+
+### Data Flow
+
+```
+User → MCP Server → resolveProjectIdAsync()
+                      ↓
+                   Check cache
+                      ↓ (miss)
+                   getOrRegisterProject()
+                      ↓
+                   ensureSystemRegistered() → API
+                      ↓
+                   registerProject() → API
+                      ↓
+                   updateProjectsCache()
+                      ↓
+                   Return project_id
+```
+
+## Best Practices
+
+1. **Set API key globally**: Use environment variable or config file
+2. **Enable auto-registration**: Let the system handle project setup
+3. **One binding per project**: Don't create multiple bindings for same path
+4. **Git remotes help**: They make project identification easier
+5. **Cache is local**: Each machine has its own bindings cache
+
+## Future Enhancements
+
+- [ ] Sync bindings from API on startup
+- [ ] Detect project changes (git remote updates)
+- [ ] Multi-org support
+- [ ] Project metadata updates
+- [ ] Binding removal/cleanup
+- [ ] Cross-machine project resolution
+- [ ] Project templates