@ezmodo/mcp-server 0.13.0

package/README.md

@@ -0,0 +1,305 @@
+# EzModo MCP Server
+
+Model Context Protocol (MCP) server for ezmodo - AI-first project management.
+
+## Installation
+
+### Global Installation (Recommended)
+
+```bash
+npm install -g @ezmodo/mcp-server
+```
+
+### Local Installation
+
+For local development, use the ezmodo CLI (recommended):
+
+```bash
+# Install CLI
+curl -fsSL https://ezmodo.com/cli/install/scripts/latest/install.sh | sh
+
+# Authenticate
+ezmodo auth login
+
+# Configure MCP
+ezmodo mcp install
+```
+
+## Prerequisites
+
+1. **ezmodo Account**: Sign up at [ezmodo.com](https://ezmodo.com)
+2. **API Key**: Generate an API key in your ezmodo account settings
+
+### Generating an API Key
+
+1. Log in to [ezmodo.com](https://ezmodo.com)
+2. Navigate to **Settings** → **API Keys**
+3. Click **Generate New API Key**
+4. Copy your API key
+5. Store it securely - you won't be able to see it again!
+
+## Configuration
+
+### For Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ezmodo": {
+      "command": "ezmodo-mcp-server",
+      "env": {
+        "EZMODO_API_KEY": "your_api_key_here",
+        "EZMODO_API_URL": "https://ezmodo.com/api"
+      }
+    }
+  }
+}
+```
+
+**Configuration Options:**
+
+- `EZMODO_API_KEY` (required): Your ezmodo API key. Legacy `ZEPHLY_API_KEY` is still read as a fallback during the rebrand transition.
+- `EZMODO_API_URL` (optional): Custom API URL. Defaults to production (`https://ezmodo.com/api`).
+
+### For Local Development
+
+If running from source:
+
+```bash
+export EZMODO_API_KEY="your_api_key_here"
+export EZMODO_API_URL="http://localhost:8787/api"  # Local Go API
+npm run dev
+```
+
+## Available Tools
+
+The MCP server provides these tools for AI agents:
+
+### 1. `create_task`
+Create a new task in a project with AI context.
+
+**Parameters:**
+- `projectId` (required): Project ID
+- `title` (required): Task title
+- `description` (required): Task description (markdown supported)
+- `priority` (optional): `low`, `medium`, `high`, `urgent` (default: `medium`)
+- `assigneeType` (optional): `human` or `ai` (default: `ai`)
+- `assigneeId` (optional): Assignee identifier (default: `claude`)
+- `assigneeName` (optional): Assignee name (default: `Claude`)
+- `knowledge` (optional): Array of structured KnowledgeItem objects with `type`, `content`, and optional `tags`
+
+### 2. `update_task`
+Update an existing task.
+
+**Parameters:**
+- `taskId` (required): Task ID
+- `status` (optional): Task status
+- `priority` (optional): Task priority
+- `description` (optional): Updated description
+- `addKnowledge` (optional): Array of structured KnowledgeItem objects to add
+
+### 3. `complete_task`
+Mark a task as completed.
+
+**Parameters:**
+- `taskId` (required): Task ID
+- `completionNotes` (optional): Completion notes
+
+### 4. `get_project_context`
+Retrieve project context, configuration, and metadata.
+
+**Parameters:**
+- `projectId` (required): Project ID
+
+### 5. `add_task_context`
+Add knowledge or memory to a task for AI continuity.
+
+**Parameters:**
+- `taskId` (required): Task ID
+- `knowledge` (optional): Knowledge snippets to add
+- `memory` (optional): Memory data to store
+
+### 6. `search_tasks`
+Search for tasks with filters.
+
+**Parameters:**
+- `projectId` (optional): Filter by project
+- `status` (optional): Filter by status
+- `assignedToAI` (optional): Filter for AI-assigned tasks
+- `searchText` (optional): Text search in title/description
+- `limit` (optional): Max results (default: 50)
+
+### 7. `get_documentation`
+Retrieve project documentation.
+
+**Parameters:**
+- `projectId` (required): Project ID
+- `docType` (optional): Filter by type (`guide`, `api`, `process`, `context`)
+- `tags` (optional): Filter by tags
+
+### 8. `manage_watch`
+Watch or unwatch a task, subscribing **you** (the API key's owner) to
+notifications about its status changes and comments.
+
+You are subscribed automatically to tasks you're assigned, own, create or
+comment on, so this is for following work that isn't yours.
+
+**Parameters:**
+- `action` (required): `watch` or `unwatch`
+- `taskId` (required): The task to (un)watch
+
+Both actions are idempotent. There is deliberately no `userId` parameter — the
+acting user is always the key's owner, so an agent cannot subscribe someone else.
+
+### 9. `list_watched`
+List the tasks you're watching, with status, priority, project and when each
+last changed — enough to answer "what's happening on the work I follow?" without
+a `get_task` per row. Each result carries `reason` (`manual`, `assignee`,
+`owner` or `commenter`), why you're subscribed.
+
+**Parameters:**
+- `organizationId` (required): Organization to list for
+- `limit` (optional): Max results (default: 200)
+
+### 10. `list_notifications`
+Your in-app notifications — mentions, replies, assignments, and activity on
+watched tasks.
+
+**Parameters:**
+- `unreadOnly` (optional): Only unread (default: `true`)
+- `limit` (optional): Max results (default: 20, max: 100)
+
+## Usage Example
+
+Once configured in Claude Desktop, you can use natural language:
+
+```
+"Create a task in project abc123 titled 'Implement user authentication'
+with high priority and assign it to me"
+
+"Show me all in-progress tasks in my current project"
+
+"Mark task xyz789 as completed with notes about the implementation"
+
+"Watch task xyz789 for me"
+
+"What's changed on the tasks I'm watching?"
+```
+
+## AI Agent Guidelines
+
+### Providing URLs to Users
+
+When providing ezmodo URLs to users, **always use the actual orgSlug value** from the project context, never use placeholders.
+
+**❌ Wrong:**
+```
+View in ezmodo: https://ezmodo.com/{orgSlug}/projects/zephly/epics
+```
+
+**✅ Correct:**
+```
+View in ezmodo: https://ezmodo.com/emo/projects/zephly/epics
+```
+
+**How to get the orgSlug:**
+1. Call `get_current_project_context()` or `list_projects()` to get project data
+2. Extract the `orgSlug` field from the response
+3. Use that actual value in any URLs you provide to users
+
+**Example:**
+```javascript
+// Response from get_current_project_context():
+{
+  "projectId": "axFzraDA4yCLgVyVBFoG",
+  "projectName": "zephly",
+  "orgSlug": "emo",  // <-- Use this actual value!
+  "organizationId": "VByHaD78P7B8ky7X4NZf"
+}
+
+// Then provide URL like:
+"View your epic at: https://ezmodo.com/emo/projects/zephly/epics"
+```
+
+This ensures users can click the link and go directly to the correct resource.
+
+### Project-First Hierarchy
+
+ezmodo uses a project-first hierarchy: **Organization → Projects → Epics → Tasks**
+
+- **Project**: Primary work container - blue theme
+- **Epic**: Project-scoped milestone - orange theme
+- **Task**: Individual work item within a project
+- **Goal**: Organization-wide strategic objective (optional, links to epics)
+
+When working with the MCP tools:
+- Use `create_epic`, `get_epic`, `update_epic` for project milestones
+- Use `create_task`, `get_task`, `update_task` for work items
+- Tasks belong to projects (required) and optionally to epics
+
+## Security
+
+- **API Keys**: Your API key authenticates with the ezmodo Go API
+- **Revocable**: You can revoke API keys anytime in your ezmodo settings
+- **Rate Limiting**: API keys have rate limits to prevent abuse
+- **Audit Trail**: All API usage is logged in your ezmodo account
+
+## Troubleshooting
+
+### "Missing Authorization header"
+- Ensure `EZMODO_API_KEY` is set in your configuration
+
+### "Invalid or revoked API key"
+- Regenerate your API key in ezmodo settings
+- Ensure the key hasn't expired or been revoked
+
+### "Failed to connect to API"
+- Check your `EZMODO_API_URL` configuration
+- Verify your internet connection
+
+### Claude Desktop doesn't see the server
+- Restart Claude Desktop after updating config
+- Check the config file path is correct
+- Verify JSON syntax in `claude_desktop_config.json`
+
+## Development
+
+### Building from Source
+
+For contributors with repository access:
+
+```bash
+cd mcp-server
+npm install
+npm run dev
+```
+
+### Testing Locally
+
+1. Start the Go API locally:
+   ```bash
+   cd ../api && go run cmd/api/main.go
+   ```
+
+2. Set local API URL:
+   ```bash
+   export EZMODO_API_URL="http://localhost:8787/api"
+   export EZMODO_API_KEY="your_api_key"
+   ```
+
+3. Run MCP server:
+   ```bash
+   npm run dev
+   ```
+
+## Support
+
+- **Documentation**: [ezmodo.com/mcp/docs](https://ezmodo.com/mcp/docs)
+- **Support**: [ezmodo.com/support](https://ezmodo.com/support)
+- **Email**: support@ezmodo.com
+
+## License
+
+MIT

package/config/development.js

@@ -0,0 +1,20 @@
+/**
+ * Development Environment Configuration
+ *
+ * This config is for local development only.
+ * Points to localhost API server.
+ */
+
+export const CONFIG = {
+  environment: 'development',
+  apiUrl: 'http://localhost:8080/api',
+  webUrl: 'http://localhost:3000',
+  settingsUrl: 'http://localhost:3000/settings/api-keys',
+
+  // Environment URLs for reference/docs
+  environmentUrls: {
+    development: 'http://localhost:8080/api',
+    staging: 'https://staging.ezmodo.com/api',
+    production: 'https://ezmodo.com/api',
+  }
+};