@focus-pocus/mcp-server 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,128 @@
+# @focus-pocus/mcp-server
+
+[Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for [Focus Pocus](https://focuspocusapp.com) — manage tasks, track work, and monitor goals from any MCP client.
+
+## Quick Start
+
+### 1. Get a Personal Access Token
+
+In Focus Pocus, go to **Settings > API Access** and create a token. Copy it — it's only shown once.
+
+### 2. Configure your MCP client
+
+**Claude Code (CLI)**
+
+```bash
+claude mcp add focus-pocus \
+  -e FOCUS_POCUS_API_URL=https://api.focuspocusapp.com \
+  -e FOCUS_POCUS_TOKEN=fp_pat_your_token_here \
+  -- npx -y @focus-pocus/mcp-server
+```
+
+**Claude Desktop / JSON config**
+
+Add to your MCP settings file (e.g. `~/.claude/mcp.json` or `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "focus-pocus": {
+      "command": "npx",
+      "args": ["-y", "@focus-pocus/mcp-server"],
+      "env": {
+        "FOCUS_POCUS_API_URL": "https://api.focuspocusapp.com",
+        "FOCUS_POCUS_TOKEN": "fp_pat_your_token_here"
+      }
+    }
+  }
+}
+```
+
+**Self-hosted instance** — replace the API URL with your own (e.g. `http://localhost:3001`).
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `FOCUS_POCUS_TOKEN` | Yes | Personal Access Token from Settings > API Access |
+| `FOCUS_POCUS_API_URL` | Yes | Focus Pocus API URL (`https://api.focuspocusapp.com` or self-hosted) |
+
+## Available Tools (22)
+
+### Tasks
+
+| Tool | Description |
+|------|-------------|
+| `create_task` | Create a task with name, priority, difficulty, due date, and goal |
+| `update_task` | Update specific fields on an existing task |
+| `complete_task` | Mark a task as completed |
+| `list_tasks` | List tasks filtered by completion status or goal |
+| `get_task` | Get full task details by ID |
+| `search_tasks` | Semantic text search across tasks |
+
+### Work Tracking
+
+| Tool | Description |
+|------|-------------|
+| `start_working` | Start a work session on a task |
+| `stop_working` | Stop tracking work on a task |
+| `get_current_work` | List tasks currently being worked on |
+| `get_work_summary` | Activity summary with recent work sessions |
+| `stop_all_work` | Stop all active work sessions at once |
+
+### Goals
+
+| Tool | Description |
+|------|-------------|
+| `list_goals` | List all goals |
+| `get_goal` | Get goal details including tasks and milestones |
+| `create_goal` | Create a new goal with name, description, and color |
+| `link_task_to_goal` | Associate a task with a goal |
+
+### Insights
+
+| Tool | Description |
+|------|-------------|
+| `get_insights` | Productivity stats — overdue items, completed today, goal alignment |
+| `get_follow_up_items` | Surface stale, abandoned, or overdue tasks |
+| `find_related_tasks` | Find semantically related tasks by concept |
+
+### Collaboration
+
+| Tool | Description |
+|------|-------------|
+| `list_collaborators` | List people you collaborate with across shared goals |
+| `get_goal_collaborators` | List collaborators on a specific goal |
+| `list_tasks_for_collaborator` | List tasks for a specific collaborator |
+
+### Comments
+
+| Tool | Description |
+|------|-------------|
+| `add_comment` | Add a progress note or comment to a task |
+
+## PAT Scopes
+
+Tokens can be scoped to limit access:
+
+| Scope | Grants access to |
+|-------|-----------------|
+| `tasks:read` | list_tasks, get_task, search_tasks, find_related_tasks, get_follow_up_items |
+| `tasks:write` | create_task, update_task, complete_task |
+| `goals:read` | list_goals, get_goal |
+| `goals:write` | create_goal, link_task_to_goal |
+| `work:tracking` | start_working, stop_working, stop_all_work, get_current_work, get_work_summary |
+| `comments:write` | add_comment |
+| `collaborators:read` | list_collaborators, get_goal_collaborators, list_tasks_for_collaborator |
+
+## Security
+
+- Tokens are SHA-256 hashed at rest; the plaintext is shown only at creation
+- Per-token rate limiting (120 requests/min)
+- All mutations are logged in the Activity Log with revert support
+- Tokens can be revoked anytime from Settings > API Access
+- Secrets are redacted from error output
+
+## License
+
+MIT

package/package.json

@@ -1,10 +1,37 @@
 {
   "name": "@focus-pocus/mcp-server",
-  "version": "0.1.0",
-  "description": "MCP server for Focus-Pocus task management",
+  "version": "0.1.2",
+  "description": "Model Context Protocol (MCP) server for Focus Pocus — manage tasks, track work, and monitor goals from Claude Code or any MCP-compatible client",
   "type": "module",
+  "license": "MIT",
+  "author": "Focus Pocus",
+  "homepage": "https://focuspocusapp.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zubin-Teherani/focus-pocus.git",
+    "directory": "mcp-server"
+  },
+  "bugs": {
+    "url": "https://github.com/Zubin-Teherani/focus-pocus/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "focus-pocus",
+    "task-management",
+    "claude",
+    "claude-code",
+    "ai-tools",
+    "productivity",
+    "goals",
+    "work-tracking"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "bin": {
-    "focus-pocus-mcp": "./dist/index.js"
+    "mcp-server": "dist/index.js",
+    "focus-pocus-mcp-server": "dist/index.js"
   },
   "scripts": {
     "build": "tsc",