@claudetools/tools 0.4.0 → 0.5.1

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