motionmcp 1.0.2 → 2.0.0

package/README.md

@@ -1,6 +1,22 @@
 # Motion MCP Server
 
-A Model Context Protocol (MCP) server that provides LLMs with direct access to the Motion API for task and project management. This server implements the MCP protocol to enable seamless integration between AI assistants and Motion's productivity platform.
+An MCP (Model Context Protocol) server that gives LLMs direct access to the Motion API for projects, tasks, users, and more. Built in TypeScript with robust validation and consolidated tools to keep your client tool list lean.
+
+## Quick start (npx)
+
+Run the server without installing globally:
+
+```bash
+MOTION_API_KEY=your_motion_api_key npx motionmcp
+```
+
+Or provide the key via your shell environment and run:
+
+```bash
+npx motionmcp
+```
+
+> Tip: `npx` runs the latest published version.
 
 ## Preview
 
@@ -10,539 +26,319 @@ A Model Context Protocol (MCP) server that provides LLMs with direct access to t
 
 ## Features
 
-- **MCP Protocol Implementation**: Full Model Context Protocol support for LLM integration
-- **Motion API Integration**: Complete CRUD operations for projects, tasks, workspaces, and users
-- **18 Built-in Tools**: Comprehensive set of tools for Motion management with AI-powered intelligence
-- **Context Awareness**: Real-time workspace context, recent activity, and intelligent suggestions
-- **Smart Workspace Management**: Automatic workspace detection and selection
-- **Intelligent Search**: Semantic search across tasks and projects with relevance scoring
-- **Workload Analytics**: Comprehensive workload analysis with overdue tasks and deadline tracking
-- **Workflow Intelligence**: Smart scheduling, bulk operations, and next action suggestions
-- **Project Templates**: Pre-built project templates with intelligent task creation
-- **Enhanced Task Creation**: Supports all Motion API parameters with intelligent defaults
-- **MCP-Compliant Logging**: Structured JSON logging to stderr for debugging
-- **JSON Schema Validation**: Proper input validation and type safety
-- **Robust Error Handling**: Detailed error messages and fallback mechanisms
-- **API Key Authentication**: Secure Motion API integration
+* MCP protocol support for seamless LLM integration
+* Motion API integration for projects, tasks, users, comments, custom fields, and recurring tasks
+* **Consolidated tools** to reduce tool count (minimal, essential, all, or custom)
+* Context utilities: semantic search and lightweight context summaries
+* API key via environment variable
+* Structured JSON logging
+* **TypeScript** with strong types, validation, and robust error handling
 
 ## Prerequisites
 
-- Node.js 18 or higher
-- Motion API key (get from https://app.usemotion.com/settings/api)
+* Node.js 18 or higher
+* Motion API key from [https://app.usemotion.com/settings/api](https://app.usemotion.com/settings/api)
 
-## Providing Your Motion API Key
+## Tool Configuration
 
-The Motion MCP Server supports multiple ways to provide your API key:
+The server supports configurable tool sets to stay within MCP client limits (~100 tools across all servers). Configure via the `MOTION_MCP_TOOLS` environment variable:
+
+### Configuration options
+
+#### Minimal (3 tools)
+Best for users who need only basic functionality and want to maximize room for other MCP servers.
 
-### Environment Variable
 ```bash
-MOTION_API_KEY=your-key npx motionmcp
+MOTION_MCP_TOOLS=minimal npx motionmcp
 ```
 
-### Command Line Arguments
-```bash
-# With API key only
-npx motionmcp --api-key=your-key
+**Available tools:**
+- `motion_tasks` - Task operations (create, list, get, update, delete, move, unassign)
+- `motion_projects` - Project operations (create, list, get)
+- `motion_workspaces` - Workspace management (list, get, set_default)
 
-# With API key and custom port
-npx motionmcp --api-key=your-key --port=4000
-```
+#### Essential (7 tools, default)
+Balanced configuration with core functionality plus search, user management, and scheduling.
 
-### Config File
-Create a config file in your home directory:
 ```bash
-echo '{"apiKey": "your-key", "port": 4000}' > ~/.motionmcp.json
+# Default - no configuration needed
 npx motionmcp
+# or explicitly:
+MOTION_MCP_TOOLS=essential npx motionmcp
 ```
 
-### Interactive Prompt
-If no API key is provided through the above methods, the server will prompt you:
+**Available tools:**
+- All from Minimal, plus:
+- `motion_users` - User operations (list, current)
+- `motion_search` - Search and context utilities (content, context, smart)
+- `motion_comments` - Comment management (list, create)
+- `motion_schedules` - Schedule operations (list)
+
+#### Complete (10 tools)
+All consolidated tools for full Motion API access.
+
 ```bash
-npx motionmcp
-# Will prompt: "Please enter your Motion API key: "
+MOTION_MCP_TOOLS=complete npx motionmcp
 ```
 
-The server checks for the API key in this order:
-1. Environment variable (`MOTION_API_KEY`)
-2. Command line argument (`--api-key=`)
-3. Config file (`~/.motionmcp.json`)
-4. Interactive prompt
+**Available tools:**
+- All from Essential, plus:
+- `motion_custom_fields` - Custom field management (list, create, delete, add/remove)
+- `motion_recurring_tasks` - Recurring task management (list, create, delete)
+- `motion_statuses` - Status operations (list)
 
-## Installation
+ 
 
-1. Clone the repository
-2. Install dependencies:
-   ```bash
-   npm install
-   ```
+#### Custom
+Specify exactly which tools you need.
 
-3. Create a `.env` file based on `.env.example`:
-   ```bash
-   cp .env.example .env
-   ```
+```bash
+MOTION_MCP_TOOLS=custom:motion_tasks,motion_projects,motion_search npx motionmcp
+```
 
-4. Update the `.env` file with your Motion API key:
-   ```
-   MOTION_API_KEY=your_motion_api_key_here
-   ```
+### Consolidated Tools
 
-## Usage
+The consolidated tools reduce the total tool count by combining related operations:
 
-The Motion MCP Server runs as a Model Context Protocol server for direct LLM integration:
+- **`motion_projects`**: Single tool for core project operations
+  - Operations: `create`, `list`, `get`
+  - Example: `{"operation": "create", "name": "New Project", "workspaceName": "Personal"}`
 
-```bash
-# Run the MCP server
-npm run mcp
+- **`motion_tasks`**: Single tool for all task operations  
+  - Operations: `create`, `list`, `get`, `update`, `delete`, `move`, `unassign`
+  - Example: `{"operation": "create", "name": "New Task", "projectName": "My Project"}`
 
-# Or run directly
-node src/mcp-server.js
-```
+- **`motion_comments`**: Manage task comments
+  - Operations: `list`, `create`
+  - Example: `{"operation": "create", "taskId": "task_123", "content": "Great progress!"}`
 
-## MCP Tools
-
-The MCP server provides 18 intelligent tools for Motion integration with enhanced AI capabilities:
-
-### Context & Intelligence
-- `get_motion_context` - Get comprehensive workspace context, recent activity, and smart suggestions
-- `search_motion_content` - Intelligent search across tasks and projects with semantic relevance
-- `analyze_motion_workload` - Analyze workload distribution, overdue tasks, and productivity insights
-- `suggest_next_actions` - AI-powered suggestions for next actions based on current state
-
-### Project Management
-- `create_motion_project` - Create a new project with workspace auto-detection
-- `create_project_template` - Create projects from intelligent templates (software dev, marketing, etc.)
-- `list_motion_projects` - List projects with workspace filtering support
-- `get_motion_project` - Get project details by ID
-- `update_motion_project` - Update project properties
-- `delete_motion_project` - Delete a project
-
-### Task Management
-- `create_motion_task` - Create a new task with intelligent workspace/project resolution
-- `list_motion_tasks` - List tasks with workspace and project filtering
-- `get_motion_task` - Get task details by ID
-- `update_motion_task` - Update task properties
-- `delete_motion_task` - Delete a task
-- `bulk_update_tasks` - Update multiple tasks simultaneously
-- `smart_schedule_tasks` - AI-powered intelligent task scheduling
-
-### Workspace & User Info
-- `list_motion_workspaces` - List all workspaces with enhanced details
-- `list_motion_users` - List all users
-
-## Enhanced Tool Features
-
-### Smart Workspace Management
-- **Auto-detection**: Automatically uses default workspace when none specified
-- **Name resolution**: Find workspaces by name instead of requiring IDs
-- **Intelligent defaults**: Prefers "Personal" workspaces as default
-- **Fallback handling**: Graceful handling when workspace resolution fails
-
-### Advanced Task Creation
-The `create_motion_task` tool now supports all Motion API parameters:
-
-**Basic Parameters:**
-- `name` (required) - Task title
-- `description` - Markdown-supported task description
-- `workspaceId` / `workspaceName` - Workspace specification (auto-detects if omitted)
-- `projectId` / `projectName` - Project assignment (optional)
-
-**Advanced Parameters:**
-- `status` - Task status (uses workspace default if omitted)
-- `priority` - ASAP, HIGH, MEDIUM, or LOW
-- `dueDate` - ISO 8601 date (required for scheduled tasks)
-- `duration` - Minutes (number), "NONE", or "REMINDER"
-- `assigneeId` - User ID for task assignment
-- `labels` - Array of label names
-- `autoScheduled` - Auto-scheduling configuration (object or null)
-
-### Intelligent Project Resolution
-- **Name lookup**: Find projects by partial or exact name match
-- **Workspace scoping**: Project searches are scoped to specific workspaces
-- **Fuzzy matching**: Supports partial name matching for easier use
-- **Error feedback**: Clear messages when projects aren't found
-
-## AI-Powered Intelligence Features
-
-### Context Awareness
-The `get_motion_context` tool provides LLMs with comprehensive situational awareness:
-
-**Real-time Context:**
-- Current default workspace and available workspaces
-- User information and permissions
-- Recent activity across tasks and projects
-- Current workload distribution and status
-
-**Intelligent Suggestions:**
-- Overdue tasks requiring immediate attention
-- High-priority items to focus on next
-- Upcoming deadlines and time-sensitive work
-- Project status insights and recommendations
-
-**Example Usage:**
-```
-LLM: Let me get your current Motion context to understand your situation.
-Tool: get_motion_context
-Result: You're in "Development" workspace with 15 active tasks. You have 3 overdue tasks and 5 high-priority items. Recent activity shows focus on "API Integration" project.
-Suggestions:
-- Address 3 overdue tasks (Task A, B, C)
-- Continue work on high-priority "Security Review"
-- Upcoming deadline: "Release Planning" due tomorrow
-```
+- **`motion_custom_fields`**: Single tool for custom field management
+  - Operations: `list`, `create`, `delete`, `add_to_project`, `remove_from_project`, `add_to_task`, `remove_from_task`
+  - Example: `{"operation": "create", "name": "Priority Level", "type": "DROPDOWN", "options": ["Low", "Medium", "High"]}`
 
-### Intelligent Search
-The `search_motion_content` tool provides semantic search capabilities:
+- **`motion_recurring_tasks`**: Single tool for recurring task templates
+  - Operations: `list`, `create`, `delete`
+  - Example: `{"operation": "create", "name": "Weekly Review", "workspaceId": "ws_123", "assigneeId": "user_123", "frequency": {"type": "weekly", "daysOfWeek": [1,3,5] }, "duration": 30 }`
 
-**Advanced Search Features:**
-- Content-aware search across task descriptions and project details
-- Relevance scoring based on exact matches, partial matches, and priority
-- Scoped search (tasks only, projects only, or both)
-- Priority boosting for urgent items
+## Providing Your Motion API Key
 
-**Example Usage:**
-```
-LLM: Let me search for anything related to "API security"
-Tool: search_motion_content
-Args: {"query": "API security", "searchScope": "both"}
-Result: Found 4 relevant items:
-- [task] API Security Review (ID: task_789) - Relevance: 95
-- [project] Security Audit (ID: proj_456) - Relevance: 70
-- [task] Update API documentation (ID: task_012) - Relevance: 45
+The Motion MCP Server supports the following ways to provide your API key:
+
+### 1. Environment Variable
+
+```bash
+MOTION_API_KEY=your-key npx motionmcp
 ```
 
-### Workload Analytics
-The `analyze_motion_workload` tool provides comprehensive productivity insights:
+### 2. .env file (when running via npm)
 
-**Analytics Capabilities:**
-- Task distribution by status, priority, and project
-- Overdue task identification and counting
-- Upcoming deadline tracking and alerts
-- Project health and progress monitoring
-- Time-based analysis (today, this week, this month)
+Create a `.env` next to the project with:
 
-**Example Usage:**
-```
-LLM: Let me analyze your current workload.
-Tool: analyze_motion_workload
-Args: {"timeframe": "this_week", "includeProjects": true}
-Result: Workload Analysis (this_week):
-- Total Tasks: 23
-- Overdue Tasks: 3
-- Upcoming Deadlines: 7
-- Task Distribution:
-  - In Progress: 8 tasks
-  - Todo: 12 tasks
-  - Completed: 3 tasks
-- Project Insights:
-  - 4 active projects
-  - 2 projects behind schedule
+```bash
+MOTION_API_KEY=your-key
 ```
 
-### Smart Scheduling
-The `smart_schedule_tasks` tool provides AI-powered task optimization:
+> When using npx, prefer exporting the variable in your shell as shown above.
 
-**Intelligent Scheduling Features:**
-- Priority-based task ordering (ASAP → HIGH → MEDIUM → LOW)
-- Deadline-aware scheduling with urgency detection
-- Workload balancing and buffer time inclusion
-- Conflict detection and resolution suggestions
-- Automatic unscheduled task discovery
+## Tool Overview
 
-**Example Usage:**
-```
-LLM: Let me intelligently schedule your unscheduled tasks.
-Tool: smart_schedule_tasks
-Args: {"schedulingPreferences": {"prioritizeDeadlines": true}}
-Result: Scheduled 8 tasks optimally:
-- Task ID: task_456 -> 9:00 AM (ASAP priority)
-- Task ID: task_789 -> 10:30 AM (Due today)
-- Task ID: task_012 -> 2:00 PM (HIGH priority)
-```
+### Context & Search
 
-### Workflow Intelligence
-The `suggest_next_actions` tool provides proactive assistance:
+* `motion_search` — content search, context, and smart search
 
-**Smart Suggestions Based On:**
-- Current task priorities and deadlines
-- Project status and momentum
-- Historical patterns and preferences
-- Workload balance and capacity
-- Context-aware recommendations (daily planning, project review, etc.)
+### Projects
 
-**Example Usage:**
-```
-LLM: What should I focus on next?
-Tool: suggest_next_actions
-Args: {"context": "daily planning", "maxSuggestions": 3}
-Result: Suggested Next Actions:
-✅ Complete "Security Review" (task_789) - ASAP priority, due today
-⏰ Start "Database Migration" (task_456) - Due in 2 days
-🔄 Review stalled project: "Mobile App" - No recent activity
-```
+* `motion_projects` — create, list, get
 
-## Quick Start for LLM Context
+### Tasks
 
-**For optimal LLM assistance, start with these tools:**
+* `motion_tasks` — create, list, get, update, delete, move, unassign
 
-1. **`get_motion_context`** - Get comprehensive workspace overview and current state
-2. **`analyze_motion_workload`** - Understand current workload and priorities
-3. **`suggest_next_actions`** - Get AI-powered recommendations for what to focus on next
+### Comments, Custom Fields, Recurring
 
-**Example Intelligent Workflow:**
-```
-User: "Help me plan my day"
+* `motion_comments` — list, create (task comments)
+* `motion_custom_fields` — list, create, delete, add/remove on project or task
+* `motion_recurring_tasks` — list, create, delete
 
-LLM: I'll help you plan your day efficiently. Let me first understand your current situation.
+### Workspaces, Users, Schedules, Statuses
 
-1. Getting your Motion context...
-Tool: get_motion_context
-Result: You're in "Work" workspace with 12 active tasks, 2 overdue items, and 4 high-priority tasks.
+* `motion_workspaces` — list, get, set_default
+* `motion_users` — list (by workspace), current
+* `motion_schedules` — user schedules and time zones
+* `motion_statuses` — available statuses by workspace
 
-2. Analyzing your current workload...
-Tool: analyze_motion_workload
-Args: {"timeframe": "today"}
-Result: Today you have 6 tasks, 2 are overdue, 3 due by end of day.
+## Enhanced Features
 
-3. Generating smart suggestions...
-Tool: suggest_next_actions
-Args: {"context": "daily planning"}
-Result: Recommended focus:
-- ✅ Complete overdue "Security Review" (ASAP priority)
-- ⏰ Finish "Database Migration" (due today)
-- 🚀 Start "Feature Testing" (high priority, good momentum)
+### Smart Defaults & Resolution
 
-Based on this analysis, I recommend starting with the overdue Security Review task since it's marked ASAP priority, then moving to the Database Migration that's due today. This will clear your urgent items and give you momentum for the day.
+* Workspace and project auto-detection and fuzzy matching
+* Intelligent defaults: selects "Personal" workspace if none provided
+* Robust fallback and error messaging
 
-Would you like me to help schedule these tasks or create any new tasks for your day?
-```
+### Task Creation
 
-## MCP Integration Examples
+Supports all Motion API parameters:
 
-### Using with Claude Desktop
-Add to your `claude_desktop_config.json`:
+* Basic: `name`, `description`, `workspaceId|workspaceName`, `projectId|projectName`
+* Advanced: `priority`, `dueDate`, `duration`, `labels`, `assigneeId`, `autoScheduled`
 
-```json
-{
-  "mcpServers": {
-    "motion": {
-      "command": "node",
-      "args": ["/path/to/MotionMCP/src/mcp-server.js"],
-      "env": {
-        "MOTION_API_KEY": "your_motion_api_key_here"
-      }
-    }
-  }
-}
-```
+### Semantic Search
 
-### LLM Tool Usage Examples
+* Cross-search by query with intelligent scope and priority boosting
 
-**Create a simple task:**
-```
-LLM: I'll create a new task for you.
-Tool: create_motion_task
-Args: {"name": "Review quarterly reports"}
-Result: Successfully created task "Review quarterly reports" with ID: task_123 in workspace ws_456
-```
+### Scheduling & Workload
 
-**Create an advanced task with project assignment:**
-```
-LLM: I'll create a detailed task in your development project.
-Tool: create_motion_task
+* Prioritized scheduling with conflict detection and task balancing
+* Detailed workload breakdowns by status, priority, and project
+
+## Example Tool Use
+
+### Creating a task with the consolidated tool
+```json
+Tool: motion_tasks
 Args: {
+  "operation": "create",
   "name": "Complete API integration",
-  "description": "Integrate with Motion API and test all endpoints",
   "workspaceName": "Development",
-  "projectName": "Feature Release",
+  "projectName": "Release Cycle Q2",
+  "dueDate": "2025-06-15T09:00:00Z",
   "priority": "HIGH",
-  "dueDate": "2025-05-30T17:00:00.000Z",
-  "duration": 120,
-  "labels": ["api", "integration", "urgent"]
+  "labels": ["api", "release"]
 }
-Result: Successfully created task "Complete API integration" with ID: task_789 in project proj_456 in workspace ws_123
 ```
 
-**List projects with workspace filtering:**
-```
-LLM: Let me check your development projects.
-Tool: list_motion_projects
-Args: {"workspaceName": "Development"}
-Result: Found 3 projects in Development workspace:
-- Feature Release (ID: proj_456) - Status: In Progress
-- Bug Fixes (ID: proj_789) - Status: Todo
-- Documentation (ID: proj_012) - Status: Backlog
+### Adding a comment to a task
+```json
+Tool: motion_comments
+Args: {
+  "operation": "create",
+  "taskId": "task_123",
+  "content": "Updated the API endpoints as discussed"
+}
 ```
 
-**List tasks with intelligent filtering:**
-```
-LLM: Let me check your current tasks.
-Tool: list_motion_tasks
-Args: {"workspaceName": "Personal", "projectName": "Website Redesign"}
-Result: Found 5 tasks in Website Redesign project:
-- Fix responsive layout (ID: task_456) - Status: In Progress
-- Update color scheme (ID: task_789) - Status: Todo
-- Optimize images (ID: task_012) - Status: Done
-- Test on mobile (ID: task_345) - Status: Todo
-- Deploy to staging (ID: task_678) - Status: Backlog
+### Creating a custom field
+```json
+Tool: motion_custom_fields
+Args: {
+  "operation": "create",
+  "name": "Sprint",
+  "type": "DROPDOWN",
+  "options": ["Sprint 1", "Sprint 2", "Sprint 3"],
+  "workspaceName": "Development"
+}
 ```
 
-## Configuration
-
-### Environment Variables
-
-| Variable         | Description                    | Default |
-| ---------------- | ------------------------------ | ------- |
-| `MOTION_API_KEY` | Your Motion API key (required) | -       |
-
-## Motion API Documentation
-
-For detailed information about Motion's API, visit: https://docs.usemotion.com/
-
-## Error Handling & Logging
-
-The server includes comprehensive error handling and MCP-compliant logging:
-
-### MCP-Compliant Logging
-- **Structured JSON logs** to stderr for MCP compliance
-- **Detailed context** including method names, IDs, and API responses
-- **Error tracking** with API status codes and messages
-- **Performance monitoring** with request/response timing
-
-### Enhanced Error Handling
-- **Smart workspace resolution** with fallback to defaults
-- **Project lookup validation** with helpful error messages
-- **API response structure handling** for wrapped/unwrapped responses
-- **Input validation** with detailed parameter requirements
-- **Graceful degradation** when optional features fail
-
-### Error Response Examples
+### Creating a recurring task
 ```json
-// Missing workspace error
-{"error": "workspaceId is required and no default workspace could be found"}
-
-// Project not found error
-{"error": "Project 'Marketing Campaign' not found in workspace"}
-
-// Invalid parameter error
-{"error": "Task priority must be one of: ASAP, HIGH, MEDIUM, LOW"}
+Tool: motion_recurring_tasks
+Args: {
+  "operation": "create",
+  "name": "Weekly Team Standup",
+  "recurrence": "WEEKLY",
+  "projectName": "Team Meetings",
+  "daysOfWeek": ["MONDAY", "WEDNESDAY", "FRIDAY"],
+  "duration": 30
+}
 ```
 
-## Security
-
-- API keys are never logged or exposed
-- All sensitive information is kept out of logs
-- Input validation on all endpoints
-- MCP-compliant structured logging to stderr
-- Workspace-scoped operations for data isolation
+## LLM Integration
 
-## Architecture
+### Claude Desktop Configuration
 
-The Motion MCP Server is designed as a focused MCP implementation:
+Add this to your `claude_desktop_config.json`.
 
-```
-src/
-├── mcp-server.js     # MCP protocol server implementation
-├── services/
-│   └── motionApi.js  # Enhanced Motion API service layer
-└── utils/            # Utility functions
+#### Using published package (npx)
+```json
+{
+  "mcpServers": {
+    "motion": {
+      "command": "npx",
+      "args": ["motionmcp"],
+      "env": {
+        "MOTION_API_KEY": "your_api_key",
+        "MOTION_MCP_TOOLS": "essential"
+      }
+    }
+  }
+}
 ```
 
-### Key Components
-
-**MotionApiService (`motionApi.js`):**
-- **Smart workspace detection** with default workspace resolution
-- **Project lookup by name** with fuzzy matching capabilities
-- **Enhanced error handling** with detailed context and fallbacks
-- **MCP-compliant logging** with structured JSON output
-- **API response handling** for Motion's wrapped response formats
-
-**MCP Server (`mcp-server.js`):**
-- **Intelligent parameter resolution** for workspace and project names
-- **Enhanced tool definitions** with comprehensive parameter documentation
-- **Robust error handling** with user-friendly error messages
-- **Workspace-aware operations** for all project and task management
-
-## Recent Improvements
-
-### Version 2.0 Enhancements
-- ✅ **MCP-Compliant Logging**: Replaced Winston with structured JSON logging to stderr
-- ✅ **Smart Workspace Management**: Auto-detection and intelligent defaults for workspaces
-- ✅ **Enhanced Task Creation**: Support for all Motion API parameters with intelligent resolution
-- ✅ **Project Name Resolution**: Find projects by name with fuzzy matching
-- ✅ **Robust Error Handling**: Detailed error messages with context and fallback mechanisms
-- ✅ **API Response Handling**: Fixed handling of Motion's wrapped response formats (`{projects: [...]}`, `{workspaces: [...]}`)
-- ✅ **Workspace-Aware Operations**: All tools now support workspace filtering and auto-detection
-- ✅ **Improved Documentation**: Comprehensive parameter descriptions and usage examples
-
-### Version 2.1 Intelligence Enhancements
-- ✅ **Context Awareness**: Real-time workspace context with activity tracking and intelligent suggestions
-- ✅ **Intelligent Search**: Semantic search across tasks and projects with relevance scoring
-- ✅ **Workload Analytics**: Comprehensive workload analysis with overdue tasks and deadline tracking
-- ✅ **Smart Scheduling**: AI-powered task scheduling with priority and deadline optimization
-- ✅ **Workflow Intelligence**: Proactive next action suggestions based on current state
-- ✅ **Project Templates**: Pre-built intelligent templates for common project types
-- ✅ **Bulk Operations**: Efficient batch updates for multiple tasks simultaneously
-- ✅ **Enhanced Tool Count**: Expanded from 12 to 18 tools with AI-powered capabilities
-
-### Breaking Changes
-- **Logging Format**: Changed from Winston file logging to MCP-compliant JSON stderr logging
-- **Task Creation**: `workspaceId` is now auto-resolved if not provided (was previously required)
-- **Response Handling**: Fixed array method errors by properly handling wrapped API responses
-
-## Debugging & Troubleshooting
-
-### MCP Logging
-The server outputs structured JSON logs to stderr for debugging:
+#### Using your local workspace (npm)
 ```json
-{"level":"info","msg":"Successfully fetched projects","method":"getProjects","count":3,"workspaceId":"ws_123","time":"2025-05-26T22:30:45.123Z"}
-{"level":"error","msg":"Failed to create task","method":"createTask","error":"workspaceId is required","time":"2025-05-26T22:30:46.456Z"}
+{
+  "mcpServers": {
+    "motion": {
+      "command": "npm",
+      "args": ["run", "mcp:dev"],
+      "cwd": "/absolute/path/to/your/MotionMCP",
+      "env": {
+        "MOTION_API_KEY": "your_api_key",
+        "MOTION_MCP_TOOLS": "essential"
+      }
+    }
+  }
+}
 ```
 
-### Common Issues
+See the full developer setup and more options in [DEVELOPER.md](./DEVELOPER.md).
 
-**Task Creation Fails:**
-- Ensure your Motion API key has task creation permissions
-- Check that the workspace exists and is accessible
-- Verify project names are spelled correctly (uses fuzzy matching)
+### Configuration Examples
 
-**Workspace Not Found:**
-- List workspaces first with `list_motion_workspaces`
-- Use exact workspace names or IDs
-- Check API key permissions for workspace access
+**Minimal setup (3 tools only):**
+```json
+{
+  "mcpServers": {
+    "motion": {
+      "command": "npx",
+      "args": ["motionmcp"],
+      "env": {
+        "MOTION_API_KEY": "your_api_key",
+        "MOTION_MCP_TOOLS": "minimal"
+      }
+    }
+  }
+}
+```
 
-**Project Resolution Issues:**
-- Projects are searched within the specified workspace only
-- Use partial names for fuzzy matching: "Marketing" will find "Marketing Campaign"
-- Ensure the project exists in the target workspace
+**Custom tools selection:**
+```json
+{
+  "mcpServers": {
+    "motion": {
+      "command": "npx",
+      "args": ["motionmcp"],
+      "env": {
+        "MOTION_API_KEY": "your_api_key",
+    "MOTION_MCP_TOOLS": "custom:motion_tasks,motion_projects,motion_search"
+      }
+    }
+  }
+}
+```
 
-### Debugging Tips
-1. **Check stderr output** for detailed MCP logs
-2. **Use `list_motion_workspaces`** to see available workspaces
-3. **Test with simple task creation** before using advanced parameters
-4. **Verify API key permissions** in Motion settings
+## Debugging
 
-## How MCP Communication Works
+* Logs output to `stderr` in JSON format
+* Check for missing keys, workspace/project names, and permissions
+* Use `motion_workspaces` (list) and `motion_projects` (list) to validate IDs
 
-1. **LLM Discovery**: LLM calls `tools/list` to discover available tools
-2. **Tool Schema**: Server returns JSON schemas for each tool
-3. **Tool Execution**: LLM calls `tools/call` with tool name and arguments
-4. **Response**: Server executes Motion API call and returns structured result
+## Logging Example
 
-**Example Protocol Flow:**
 ```json
-// LLM requests available tools
-{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}
-
-// Server responds with tool definitions
-{"jsonrpc": "2.0", "id": 1, "result": {"tools": [...]}}
-
-// LLM calls a tool
-{"jsonrpc": "2.0", "id": 2, "method": "tools/call",
- "params": {"name": "create_motion_task", "arguments": {...}}}
-
-// Server executes and responds
-{"jsonrpc": "2.0", "id": 2, "result": {"content": [...]}}
+{
+  "level": "info",
+  "msg": "Task created successfully",
+  "method": "createTask",
+  "taskId": "task_789",
+  "workspace": "Development"
+}
 ```
 
 ## License
 
-ISC
+Apache-2.0 License
+
+---
+
+For more information, see the full [Motion API docs](https://docs.usemotion.com/) or [Model Context Protocol docs](https://modelcontextprotocol.io/docs/).