@focus-pocus/mcp-server 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,46 @@
+import { Config } from './config.js';
+export declare class FocusPocusClient {
+    private baseUrl;
+    private token;
+    constructor(config: Config);
+    private request;
+    listTasks(params?: {
+        completed?: boolean;
+        goalId?: string;
+        collaboratorId?: string;
+    }): Promise<unknown>;
+    getTask(id: string): Promise<unknown>;
+    createTask(data: {
+        name: string;
+        description?: string;
+        priority?: string;
+        difficulty?: string;
+        dueDate?: string;
+        goalId?: string;
+    }): Promise<unknown>;
+    updateTask(id: string, updates: Array<{
+        field: string;
+        value: unknown;
+    }>): Promise<unknown>;
+    completeTask(id: string): Promise<unknown>;
+    searchTasks(query: string): Promise<unknown>;
+    getFollowUpItems(): Promise<unknown>;
+    findRelatedTasks(query: string, limit?: number): Promise<unknown>;
+    startWorking(taskId: string): Promise<unknown>;
+    stopWorking(taskId: string): Promise<unknown>;
+    getCurrentWork(): Promise<unknown>;
+    getWorkSummary(): Promise<unknown>;
+    stopAllWork(): Promise<unknown>;
+    listGoals(): Promise<unknown>;
+    getGoal(id: string): Promise<unknown>;
+    createGoal(data: {
+        name: string;
+        description?: string;
+        color?: string;
+    }): Promise<unknown>;
+    linkTaskToGoal(taskId: string, goalId: string): Promise<unknown>;
+    getInsights(): Promise<unknown>;
+    listCollaborators(): Promise<unknown>;
+    getGoalCollaborators(goalId: string): Promise<unknown>;
+    addComment(taskId: string, body: string): Promise<unknown>;
+}

package/dist/client.js

@@ -0,0 +1,125 @@
+export class FocusPocusClient {
+    baseUrl;
+    token;
+    constructor(config) {
+        this.baseUrl = config.apiUrl;
+        this.token = config.token;
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}/api/v1${path}`;
+        const headers = {
+            Authorization: `Bearer ${this.token}`,
+            'Content-Type': 'application/json',
+        };
+        const res = await fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            let message;
+            try {
+                const json = JSON.parse(text);
+                message = json.error || json.message || text;
+            }
+            catch {
+                message = text;
+            }
+            const safeMessage = message.length > 200 ? message.substring(0, 200) + '...' : message;
+            throw new Error(`API error ${res.status}: ${safeMessage}`);
+        }
+        if (res.status === 204 || res.headers.get('content-length') === '0') {
+            return undefined;
+        }
+        return res.json();
+    }
+    // Tasks
+    async listTasks(params) {
+        const query = new URLSearchParams();
+        if (params?.completed !== undefined) {
+            query.set('completed', String(params.completed));
+        }
+        if (params?.goalId)
+            query.set('goalId', params.goalId);
+        if (params?.collaboratorId)
+            query.set('collaboratorId', params.collaboratorId);
+        const qs = query.toString();
+        return this.request('GET', `/tasks${qs ? `?${qs}` : ''}`);
+    }
+    async getTask(id) {
+        return this.request('GET', `/tasks/${id}`);
+    }
+    async createTask(data) {
+        return this.request('POST', '/tasks', data);
+    }
+    async updateTask(id, updates) {
+        return this.request('PUT', `/tasks/${id}`, { id, updates });
+    }
+    async completeTask(id) {
+        return this.updateTask(id, [
+            { field: 'completed', value: true },
+        ]);
+    }
+    async searchTasks(query) {
+        const params = new URLSearchParams({ q: query });
+        return this.request('GET', `/tasks/search?${params.toString()}`);
+    }
+    async getFollowUpItems() {
+        return this.request('GET', '/tasks/stale');
+    }
+    async findRelatedTasks(query, limit) {
+        const params = new URLSearchParams({
+            q: query,
+            excludeCompleted: 'true',
+            excludeExpired: 'true',
+        });
+        if (limit)
+            params.set('limit', String(limit));
+        return this.request('GET', `/tasks/search?${params.toString()}`);
+    }
+    // Work tracking
+    async startWorking(taskId) {
+        return this.request('POST', `/tasks/${taskId}/start-working`);
+    }
+    async stopWorking(taskId) {
+        return this.request('POST', `/tasks/${taskId}/stop-working`);
+    }
+    async getCurrentWork() {
+        return this.request('GET', '/current-work');
+    }
+    async getWorkSummary() {
+        return this.request('GET', '/current-work/summary');
+    }
+    async stopAllWork() {
+        return this.request('POST', '/current-work/stop-all');
+    }
+    // Goals
+    async listGoals() {
+        return this.request('GET', '/goals');
+    }
+    async getGoal(id) {
+        return this.request('GET', `/goals/${id}`);
+    }
+    async createGoal(data) {
+        return this.request('POST', '/goals', data);
+    }
+    async linkTaskToGoal(taskId, goalId) {
+        return this.request('POST', `/tasks/${taskId}/link-to-goal`, { goalId });
+    }
+    // Insights
+    async getInsights() {
+        return this.request('GET', '/insights');
+    }
+    // Collaborators
+    async listCollaborators() {
+        return this.request('GET', '/collaborators');
+    }
+    async getGoalCollaborators(goalId) {
+        return this.request('GET', `/goals/${goalId}/collaborators`);
+    }
+    // Comments
+    async addComment(taskId, body) {
+        return this.request('POST', `/tasks/${taskId}/comments`, { body });
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,5 @@
+export interface Config {
+    apiUrl: string;
+    token: string;
+}
+export declare function loadConfig(): Config;

package/dist/config.js

@@ -0,0 +1,22 @@
+export function loadConfig() {
+    const apiUrl = process.env.FOCUS_POCUS_API_URL;
+    const token = process.env.FOCUS_POCUS_TOKEN;
+    if (!apiUrl) {
+        throw new Error('FOCUS_POCUS_API_URL environment variable is required');
+    }
+    if (!token) {
+        throw new Error('FOCUS_POCUS_TOKEN environment variable is required');
+    }
+    // Validate URL to prevent SSRF
+    let parsed;
+    try {
+        parsed = new URL(apiUrl);
+    }
+    catch {
+        throw new Error('FOCUS_POCUS_API_URL must be a valid URL');
+    }
+    if (!['http:', 'https:'].includes(parsed.protocol)) {
+        throw new Error('FOCUS_POCUS_API_URL must use http or https protocol');
+    }
+    return { apiUrl: apiUrl.replace(/\/$/, ''), token };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { loadConfig } from './config.js';
+import { createServer } from './server.js';
+async function main() {
+    const config = loadConfig();
+    const server = createServer(config);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    const redacted = message.replace(/fp_pat_[a-f0-9]+/gi, 'fp_pat_[REDACTED]');
+    console.error('Fatal error:', redacted);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Config } from './config.js';
+export declare function createServer(config: Config): McpServer;

package/dist/server.js

@@ -0,0 +1,43 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { FocusPocusClient } from './client.js';
+import { registerTaskTools } from './tools/tasks.js';
+import { registerWorkTrackingTools } from './tools/workTracking.js';
+import { registerGoalTools } from './tools/goals.js';
+import { registerCommentTools } from './tools/comments.js';
+import { registerInsightTools } from './tools/insights.js';
+import { registerCollaboratorTools } from './tools/collaborators.js';
+const INSTRUCTIONS = `Focus Pocus is a task and goal management system. Use these tools to manage tasks, track work, and monitor progress.
+
+## Recommended workflow
+
+1. **Before creating a task**, use search_tasks to check for duplicates.
+2. **When starting work** on a task, call start_working to track it. Call stop_working when done.
+3. **Log progress** with add_comment as you hit milestones or make decisions.
+4. **Link tasks to goals** using the goalId parameter on create_task or update_task. Use list_goals to find goal IDs.
+5. **When work is finished**, call complete_task to mark it done.
+
+## Tool groups
+
+- **Tasks**: create_task, update_task, complete_task, list_tasks, get_task, search_tasks
+- **Work tracking**: start_working, stop_working, stop_all_work, get_current_work, get_work_summary
+- **Goals**: list_goals, get_goal
+- **Insights**: get_insights (productivity stats), get_follow_up_items (stale/abandoned tasks), find_related_tasks (semantic similarity)
+- **Collaboration**: list_collaborators, get_goal_collaborators, list_tasks_for_collaborator
+- **Comments**: add_comment
+`;
+export function createServer(config) {
+    const server = new McpServer({
+        name: 'focus-pocus',
+        version: '0.1.0',
+    }, {
+        instructions: INSTRUCTIONS,
+    });
+    const client = new FocusPocusClient(config);
+    registerTaskTools(server, client);
+    registerWorkTrackingTools(server, client);
+    registerGoalTools(server, client);
+    registerCommentTools(server, client);
+    registerInsightTools(server, client);
+    registerCollaboratorTools(server, client);
+    return server;
+}

package/dist/tools/collaborators.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { FocusPocusClient } from '../client.js';
+export declare function registerCollaboratorTools(server: McpServer, client: FocusPocusClient): void;

package/dist/tools/collaborators.js

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+export function registerCollaboratorTools(server, client) {
+    server.tool('list_collaborators', 'List all collaborators across your shared goals. Returns a deduplicated list of people you collaborate with (excludes yourself).', {}, async () => {
+        const result = await client.listCollaborators();
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool('get_goal_collaborators', 'List collaborators on a specific goal, including the goal owner.', { goalId: z.string().describe('Goal ID (UUID)') }, async ({ goalId }) => {
+        const result = await client.getGoalCollaborators(goalId);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool('list_tasks_for_collaborator', 'List tasks created by or assigned to a specific collaborator. Useful for checking a teammate\'s workload or finding overdue items.', {
+        collaboratorId: z.string().describe('User ID (UUID) of the collaborator'),
+        completed: z.boolean().optional().describe('Filter by completion status. Defaults to false (active tasks).'),
+        goalId: z.string().optional().describe('Filter to tasks in a specific goal'),
+    }, async ({ collaboratorId, completed, goalId }) => {
+        const result = await client.listTasks({ collaboratorId, completed, goalId });
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/tools/comments.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { FocusPocusClient } from '../client.js';
+export declare function registerCommentTools(server: McpServer, client: FocusPocusClient): void;

package/dist/tools/comments.js

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+export function registerCommentTools(server, client) {
+    server.tool('add_comment', 'Add a comment to a task. Useful for logging progress notes or context.', {
+        taskId: z.string().describe('Task ID (UUID) to comment on'),
+        body: z.string().describe('Comment text content'),
+    }, async ({ taskId, body }) => {
+        const result = await client.addComment(taskId, body);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/tools/goals.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { FocusPocusClient } from '../client.js';
+export declare function registerGoalTools(server: McpServer, client: FocusPocusClient): void;

package/dist/tools/goals.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+export function registerGoalTools(server, client) {
+    server.tool('list_goals', 'List all goals. Useful for finding goal IDs to associate tasks with.', {}, async () => {
+        const result = await client.listGoals();
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool('get_goal', 'Get a specific goal by ID with full details including tasks, milestones, and collaborators.', { id: z.string().describe('Goal ID (UUID)') }, async ({ id }) => {
+        const result = await client.getGoal(id);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool('create_goal', 'Create a new goal. Goals help organize tasks toward bigger outcomes.', {
+        name: z.string().describe('Goal name/title'),
+        description: z.string().optional().describe('Goal description'),
+        color: z.string().optional().describe('Goal color (hex code, e.g. "#4CAF50")'),
+    }, async ({ name, description, color }) => {
+        const result = await client.createGoal({ name, description, color });
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool('link_task_to_goal', 'Associate a task with a goal. Moves a task under a goal for organization.', {
+        taskId: z.string().describe('Task ID (UUID) to link'),
+        goalId: z.string().describe('Goal ID (UUID) to link the task to'),
+    }, async ({ taskId, goalId }) => {
+        const result = await client.linkTaskToGoal(taskId, goalId);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/tools/insights.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { FocusPocusClient } from '../client.js';
+export declare function registerInsightTools(server: McpServer, client: FocusPocusClient): void;

package/dist/tools/insights.js

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+export function registerInsightTools(server, client) {
+    server.tool('get_follow_up_items', 'Get tasks that need attention: drafts, transferred tasks, never-started tasks (7+ days old), and abandoned tasks (14+ days since last work).', {}, async () => {
+        const result = await client.getFollowUpItems();
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool('get_insights', 'Get productivity insights: task counts, overdue items, completed today, goal alignment stats, and high priority task count.', {}, async () => {
+        const result = await client.getInsights();
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool('find_related_tasks', 'Find tasks semantically related to a concept or topic. Uses embedding-based similarity search to discover related work.', {
+        concept: z.string().describe('Concept or topic to find related tasks for (e.g., "marketing", "bug fixes", "Q1 planning")'),
+        limit: z.number().min(1).max(20).optional().describe('Maximum results to return (default: 10)'),
+    }, async ({ concept, limit }) => {
+        const result = await client.findRelatedTasks(concept, limit);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/tools/tasks.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { FocusPocusClient } from '../client.js';
+export declare function registerTaskTools(server: McpServer, client: FocusPocusClient): void;

package/dist/tools/tasks.js

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+export function registerTaskTools(server, client) {
+    server.tool('list_tasks', 'List tasks from Focus-Pocus. Returns active (incomplete) tasks by default.', {
+        completed: z.boolean().optional().describe('Filter by completion status. Defaults to false (active tasks).'),
+        goalId: z.string().optional().describe('Filter by goal ID'),
+    }, async ({ completed, goalId }) => {
+        const result = await client.listTasks({ completed, goalId });
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool('get_task', 'Get a specific task by ID with full details.', { id: z.string().describe('Task ID (UUID)') }, async ({ id }) => {
+        const result = await client.getTask(id);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool('create_task', 'Create a new task in Focus-Pocus. The task will be tagged as created via MCP.', {
+        name: z.string().describe('Task name/title'),
+        description: z.string().optional().describe('Task description'),
+        priority: z.enum(['No priority', 'Low', 'Medium', 'High']).optional().describe('Task priority'),
+        difficulty: z.enum(['Not sure', 'Small', 'Medium', 'Large']).optional().describe('Task difficulty/size'),
+        dueDate: z.string().optional().describe('Due date in ISO 8601 format'),
+        goalId: z.string().optional().describe('Goal ID to associate with'),
+    }, async ({ name, description, priority, difficulty, dueDate, goalId }) => {
+        const result = await client.createTask({
+            name, description, priority, difficulty, dueDate, goalId,
+        });
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool('update_task', 'Update an existing task. Provide only the fields you want to change.', {
+        id: z.string().describe('Task ID (UUID)'),
+        name: z.string().optional().describe('New task name'),
+        description: z.string().optional().describe('New description'),
+        priority: z.enum(['No priority', 'Low', 'Medium', 'High']).optional().describe('New priority'),
+        difficulty: z.enum(['Not sure', 'Small', 'Medium', 'Large']).optional().describe('New difficulty'),
+        dueDate: z.string().nullable().optional().describe('New due date (ISO 8601) or null to clear'),
+        goalId: z.string().nullable().optional().describe('New goal ID or null to unlink'),
+    }, async ({ id, ...fields }) => {
+        const updates = Object.entries(fields)
+            .filter(([, v]) => v !== undefined)
+            .map(([field, value]) => ({ field, value }));
+        if (updates.length === 0) {
+            return { content: [{ type: 'text', text: 'No fields to update' }], isError: true };
+        }
+        const result = await client.updateTask(id, updates);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool('complete_task', 'Mark a task as completed.', { id: z.string().describe('Task ID (UUID)') }, async ({ id }) => {
+        const result = await client.completeTask(id);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool('search_tasks', 'Search tasks by text query using semantic search.', { query: z.string().describe('Search query text') }, async ({ query }) => {
+        const result = await client.searchTasks(query);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/tools/workTracking.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { FocusPocusClient } from '../client.js';
+export declare function registerWorkTrackingTools(server: McpServer, client: FocusPocusClient): void;

package/dist/tools/workTracking.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+export function registerWorkTrackingTools(server, client) {
+    server.tool('start_working', 'Start tracking work on a task. Marks the task as currently being worked on.', { taskId: z.string().describe('Task ID (UUID) to start working on') }, async ({ taskId }) => {
+        const result = await client.startWorking(taskId);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool('stop_working', 'Stop tracking work on a task.', { taskId: z.string().describe('Task ID (UUID) to stop working on') }, async ({ taskId }) => {
+        const result = await client.stopWorking(taskId);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool('get_current_work', 'Get all tasks currently being worked on.', {}, async () => {
+        const result = await client.getCurrentWork();
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool('get_work_summary', 'Get a summary of work activity including currently working tasks and recent work.', {}, async () => {
+        const result = await client.getWorkSummary();
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool('stop_all_work', 'Stop tracking work on all tasks at once.', {}, async () => {
+        const result = await client.stopAllWork();
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@focus-pocus/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for Focus-Pocus task management",
+  "type": "module",
+  "bin": {
+    "focus-pocus-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "ESLINT_USE_FLAT_CONFIG=false eslint 'src/**/*.ts' --fix"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "eslint": "^8.57.0",
+    "typescript": "^5.7.0"
+  }
+}