brioright-mcp 1.5.0 → 1.7.0

package/index.js

@@ -503,6 +503,345 @@ function buildServer() {
         }
     )
 
+    // ── get_project_analytics ────────────────────────────────────────────────
+    server.tool('get_project_analytics',
+        'Returns detailed analytics for a specific project including: task completion rate, task counts by status/priority, and daily completion trends. Use this when the user asks "how is this project doing?", "show me the project health", or "what is the completion rate for the Lumi project?".',
+        {
+            projectId: z.string().describe('ID of the project to fetch analytics for.'),
+            workspaceId: z.string().optional().describe('Workspace slug. Defaults to BRIORIGHT_WORKSPACE_ID.'),
+            apiKey: z.string().optional().describe('Brioright API key.')
+        },
+        async ({ projectId, workspaceId, apiKey }) => {
+            const ws = workspaceId || DEFAULT_WORKSPACE
+            if (!ws) throw new Error('workspaceId is required')
+            const data = await call('GET', `/workspaces/${ws}/projects/${projectId}/analytics`, null, apiKey)
+            return { content: [{ type: 'text', text: JSON.stringify(data.analytics || data, null, 2) }] }
+        }
+    )
+
+    // ── get_project_activity ──────────────────────────────────────────────────
+    server.tool('get_project_activity',
+        'Returns the recent activity log for a specific project. Use this when the user asks "what has happened recently in this project?" or "show me the history of the Lumi app project". Returns up to 50 recent actions.',
+        {
+            projectId: z.string().describe('ID of the project to fetch activity history for.'),
+            workspaceId: z.string().optional().describe('Workspace slug. Defaults to BRIORIGHT_WORKSPACE_ID.'),
+            apiKey: z.string().optional().describe('Brioright API key.')
+        },
+        async ({ projectId, workspaceId, apiKey }) => {
+            const ws = workspaceId || DEFAULT_WORKSPACE
+            if (!ws) throw new Error('workspaceId is required')
+            const data = await call('GET', `/workspaces/${ws}/projects/${projectId}/activity`, null, apiKey)
+            const activities = data.activities || data
+            return { content: [{ type: 'text', text: JSON.stringify(activities.map(a => ({ id: a.id, type: a.type, message: a.message, user: a.user?.name, createdAt: a.createdAt })), null, 2) }] }
+        }
+    )
+
+    // ── get_active_timers ─────────────────────────────────────────────────────
+    server.tool('get_active_timers',
+        'Returns all running (active) time trackers for the current user across all projects. Use this when the user asks "do I have a timer running?", "what am I working on right now?", or "show me my active timers".',
+        {
+            workspaceId: z.string().optional().describe('Workspace slug. Defaults to BRIORIGHT_WORKSPACE_ID.'),
+            apiKey: z.string().optional().describe('Brioright API key.')
+        },
+        async ({ workspaceId, apiKey }) => {
+            const ws = workspaceId || DEFAULT_WORKSPACE
+            if (!ws) throw new Error('workspaceId is required')
+            const data = await call('GET', `/workspaces/${ws}/time-entries/active`, null, apiKey)
+            const active = data.active || data
+            return { content: [{ type: 'text', text: JSON.stringify(active, null, 2) }] }
+        }
+    )
+
+    // ── stop_timer ────────────────────────────────────────────────────────────
+    server.tool('stop_timer',
+        'Stops a running time tracker by its ID. Use this when the user says "stop my timer", "I am done with this task", or "clock me out". If you don\'t have the timer ID, call get_active_timers first.',
+        {
+            timerId: z.string().describe('The ID of the time entry to stop.'),
+            workspaceId: z.string().optional().describe('Workspace slug. Defaults to BRIORIGHT_WORKSPACE_ID.'),
+            apiKey: z.string().optional().describe('Brioright API key.')
+        },
+        async ({ timerId, workspaceId, apiKey }) => {
+            const ws = workspaceId || DEFAULT_WORKSPACE
+            if (!ws) throw new Error('workspaceId is required')
+            await call('PATCH', `/workspaces/${ws}/time-entries/${timerId}/stop`, null, apiKey)
+            return { content: [{ type: 'text', text: `✅ Timer ${timerId} stopped successfully.` }] }
+        }
+    )
+
+    // ── get_time_summary ──────────────────────────────────────────────────────
+    server.tool('get_time_summary',
+        'Returns a statistical summary of time logged by the user, aggregated by day or project. Use this when the user asks "how much did I work this week?", "show me my time stats", or "how many hours have I logged today?".',
+        {
+            workspaceId: z.string().optional().describe('Workspace slug. Defaults to BRIORIGHT_WORKSPACE_ID.'),
+            apiKey: z.string().optional().describe('Brioright API key.')
+        },
+        async ({ workspaceId, apiKey }) => {
+            const ws = workspaceId || DEFAULT_WORKSPACE
+            if (!ws) throw new Error('workspaceId is required')
+            const data = await call('GET', `/workspaces/${ws}/time-entries/summary`, null, apiKey)
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+        }
+    )
+
+    // ── get_time_entries ──────────────────────────────────────────────────────
+    server.tool('get_time_entries',
+        'Lists detailed time entry logs with optional filters for project or task. Use this when the user asks "show me my time logs for the Lumi project" or "when did I work on task X?".',
+        {
+            projectId: z.string().optional().describe('Filter by Project ID.'),
+            taskId: z.string().optional().describe('Filter by Task ID.'),
+            workspaceId: z.string().optional().describe('Workspace slug. Defaults to BRIORIGHT_WORKSPACE_ID.'),
+            apiKey: z.string().optional().describe('Brioright API key.')
+        },
+        async ({ projectId, taskId, workspaceId, apiKey }) => {
+            const ws = workspaceId || DEFAULT_WORKSPACE
+            if (!ws) throw new Error('workspaceId is required')
+            const params = new URLSearchParams()
+            if (projectId) params.set('projectId', projectId)
+            if (taskId) params.set('taskId', taskId)
+            const data = await call('GET', `/workspaces/${ws}/time-entries?${params}`, null, apiKey)
+            const entries = data.entries || data
+            return { content: [{ type: 'text', text: JSON.stringify(entries, null, 2) }] }
+        }
+    )
+
+    // ── get_task_dependencies ────────────────────────────────────────────────
+    server.tool('get_task_dependencies',
+        'Returns a list of all tasks that the specified task depends on (blockers) and tasks that depend on it. Use this when the user asks "what is blocking this task?" or "are there any dependencies for task X?". Useful for project scheduling and identifying bottlenecks.',
+        {
+            taskId: z.string().describe('ID of the task to fetch dependencies for.'),
+            workspaceId: z.string().optional().describe('Workspace slug. Defaults to BRIORIGHT_WORKSPACE_ID.'),
+            apiKey: z.string().optional().describe('Brioright API key.')
+        },
+        async ({ taskId, workspaceId, apiKey }) => {
+            const ws = workspaceId || DEFAULT_WORKSPACE
+            if (!ws) throw new Error('workspaceId is required')
+            const data = await call('GET', `/workspaces/${ws}/tasks/${taskId}/dependencies`, null, apiKey)
+            return { content: [{ type: 'text', text: JSON.stringify(data.dependencies || data, null, 2) }] }
+        }
+    )
+
+    // ── add_task_dependency ───────────────────────────────────────────────────
+    server.tool('add_task_dependency',
+        'Creates a dependency relationship between two tasks. Use this when the user says "task A depends on task B" or "task B blocks task A". In this case, task B is the blockingTaskId.',
+        {
+            taskId: z.string().describe('ID of the task that is being blocked.'),
+            blockingTaskId: z.string().describe('ID of the task that must be completed first.'),
+            workspaceId: z.string().optional().describe('Workspace slug. Defaults to BRIORIGHT_WORKSPACE_ID.'),
+            apiKey: z.string().optional().describe('Brioright API key.')
+        },
+        async ({ taskId, blockingTaskId, workspaceId, apiKey }) => {
+            const ws = workspaceId || DEFAULT_WORKSPACE
+            if (!ws) throw new Error('workspaceId is required')
+            const data = await call('POST', `/workspaces/${ws}/tasks/${taskId}/dependencies`, { blockingTaskId }, apiKey)
+            return { content: [{ type: 'text', text: `✅ Dependency added: Task ${taskId} is now blocked by Task ${blockingTaskId}.` }] }
+        }
+    )
+
+    // ── remove_task_dependency ────────────────────────────────────────────────
+    server.tool('remove_task_dependency',
+        'Removes an existing dependency between two tasks. Use this when a dependency is no longer valid or was added by mistake. Requires the dependency ID (depId), which can be found via get_task_dependencies.',
+        {
+            taskId: z.string().describe('ID of the task that was being blocked.'),
+            depId: z.string().describe('ID of the dependency relationship to remove.'),
+            workspaceId: z.string().optional().describe('Workspace slug. Defaults to BRIORIGHT_WORKSPACE_ID.'),
+            apiKey: z.string().optional().describe('Brioright API key.')
+        },
+        async ({ taskId, depId, workspaceId, apiKey }) => {
+            const ws = workspaceId || DEFAULT_WORKSPACE
+            if (!ws) throw new Error('workspaceId is required')
+            await call('DELETE', `/workspaces/${ws}/tasks/${taskId}/dependencies/${depId}`, null, apiKey)
+            return { content: [{ type: 'text', text: `✅ Dependency ${depId} removed from Task ${taskId}.` }] }
+        }
+    )
+
+    // ── search_users ──────────────────────────────────────────────────────────
+    server.tool('search_users',
+        'Allows searching for users across the entire Brioright system by name or email. Use this when you need to find a user\'s ID for task assignment and they aren\'t in the current workspace member list, or when the user says "assign this to John" and you need to find which John.',
+        {
+            query: z.string().describe('Search keyword (name or email). Minimum 2 characters.'),
+            apiKey: z.string().optional().describe('Brioright API key.')
+        },
+        async ({ query, apiKey }) => {
+            if (!query || query.trim().length < 2) throw new Error('Search query must be at least 2 characters')
+            const data = await call('GET', `/users/search?q=${encodeURIComponent(query.trim())}`, null, apiKey)
+            const users = data.users || data
+            return { content: [{ type: 'text', text: JSON.stringify(users, null, 2) }] }
+        }
+    )
+
+    // ── get_notifications ─────────────────────────────────────────────────────
+    server.tool('get_notifications',
+        'Fetches the latest unread notifications for the current user. Use this when the user asks "what are my notifications?", "has anyone replied to my comment?", or "are there any updates for me?".',
+        {
+            apiKey: z.string().optional().describe('Brioright API key.')
+        },
+        async ({ apiKey }) => {
+            const data = await call('GET', '/notifications', null, apiKey)
+            const notifications = data.notifications || data
+            return { content: [{ type: 'text', text: JSON.stringify(notifications, null, 2) }] }
+        }
+    )
+
+    // ── mark_notification_read ────────────────────────────────────────────────
+    server.tool('mark_notification_read',
+        'Marks one or all notifications as read. Use this when the user says "clear my notifications" or "mark notification X as read".',
+        {
+            notificationId: z.string().optional().describe('ID of the specific notification to mark as read. If omitted, and "all" is true, marks all read.'),
+            all: z.boolean().optional().describe('If true, marks all notifications in the workspace as read.'),
+            apiKey: z.string().optional().describe('Brioright API key.')
+        },
+        async ({ notificationId, all, apiKey }) => {
+            if (all) {
+                await call('PATCH', '/notifications/read-all', null, apiKey)
+                return { content: [{ type: 'text', text: '✅ All notifications marked as read.' }] }
+            }
+            if (!notificationId) throw new Error('Either notificationId or all=true must be provided')
+            await call('PATCH', `/notifications/${notificationId}/read`, null, apiKey)
+            return { content: [{ type: 'text', text: `✅ Notification ${notificationId} marked as read.` }] }
+        }
+    )
+
+    // ── start_work ─────────────────────────────────────────────────────────────
+    server.tool('start_work',
+        'Signals that AI has STARTED working on a task. Creates a task with status=in_progress and returns its ID. Call this at the BEGINNING of any significant work session (feature, bug fix, refactor, UI change, etc.) so the work is tracked from the start. Returns a taskId — pass it to finish_work when the work is complete. Pair: start_work → finish_work.',
+        {
+            projectId: z.string().describe('Project ID to log the work against — use list_projects if unknown.'),
+            title: z.string().describe('Clear title for the work being started, e.g. "Refactor login page UI" or "Fix avatar upload bug".'),
+            description: z.string().optional().describe('Optional: what will be done, the approach, and which files/areas will be affected.'),
+            priority: z.enum(['low', 'medium', 'high', 'urgent']).optional().default('medium').describe('Priority of the work. Use urgent for blockers.'),
+            workspaceId: z.string().optional().describe('Workspace slug. Defaults to BRIORIGHT_WORKSPACE_ID.'),
+            apiKey: z.string().optional().describe('Brioright API key.')
+        },
+        async ({ projectId, title, description, priority, workspaceId, apiKey }) => {
+            const ws = workspaceId || DEFAULT_WORKSPACE
+            if (!ws) throw new Error('workspaceId is required')
+            const startedAt = new Date().toLocaleString()
+            const data = await call('POST', `/workspaces/${ws}/projects/${projectId}/tasks`, {
+                title,
+                description: description
+                    ? `${description}\n\n---\n_🤖 Work started by AI agent at ${startedAt}_`
+                    : `🤖 Work started by AI agent at ${startedAt}.\n\n_Call \`finish_work\` with this task ID when the work is complete._`,
+                status: 'in_progress',
+                priority: priority || 'medium',
+            }, apiKey)
+            const task = data.task || data
+            return { content: [{ type: 'text', text: `🚀 Work started and logged!\n\nTask ID: **${task.id}**\nTitle: ${task.title}\nStatus: in_progress\n\n👉 Remember to call \`finish_work\` with taskId="${task.id}" when done.` }] }
+        }
+    )
+
+    // ── finish_work ─────────────────────────────────────────────────────────────
+    server.tool('finish_work',
+        'Signals that AI has COMPLETED a piece of work. Marks the task as done and posts a structured markdown completion summary as a comment (what changed, files modified, key decisions). Use this to close a task that was opened with start_work. If you did not call start_work, use track_work instead for a one-shot retroactive log.',
+        {
+            taskId: z.string().describe('Task ID returned by start_work. This is the task to mark as done.'),
+            summary: z.string().describe('What was accomplished — be specific. Describe what changed, why, and any important decisions. Markdown is supported.'),
+            filesChanged: z.array(z.string()).optional().describe('List of files that were created or modified, e.g. ["src/components/Login.jsx", "src/styles/auth.css"]. Will be shown in the completion comment.'),
+            workspaceId: z.string().optional().describe('Workspace slug. Defaults to BRIORIGHT_WORKSPACE_ID.'),
+            apiKey: z.string().optional().describe('Brioright API key.')
+        },
+        async ({ taskId, summary, filesChanged, workspaceId, apiKey }) => {
+            const ws = workspaceId || DEFAULT_WORKSPACE
+            if (!ws) throw new Error('workspaceId is required')
+
+            // Mark task as done
+            await call('PATCH', `/workspaces/${ws}/tasks/${taskId}`, { status: 'done' }, apiKey)
+
+            // Build a clean structured completion comment
+            const fileSection = filesChanged?.length
+                ? `\n\n### 📁 Files Changed\n${filesChanged.map(f => `- \`${f}\``).join('\n')}`
+                : ''
+            const comment = [
+                `## ✅ Work Completed`,
+                ``,
+                summary,
+                fileSection,
+                ``,
+                `---`,
+                `_🤖 Completed by AI agent at ${new Date().toLocaleString()}_`
+            ].join('\n')
+
+            await call('POST', `/workspaces/${ws}/tasks/${taskId}/comments`, { text: comment }, apiKey)
+
+            return { content: [{ type: 'text', text: `✅ Work finished and logged!\n\nTask ${taskId} → done\nCompletion summary posted as a comment on the task.` }] }
+        }
+    )
+
+    // ── track_work ─────────────────────────────────────────────────────────────
+    server.tool('track_work',
+        'Smart one-shot work tracker. Call this AFTER completing any work session to automatically: (1) search for an existing matching task in the project, (2) reuse it or create a fresh one if not found, (3) mark it done, and (4) post a structured completion comment. This is the preferred tool when you did not call start_work at the beginning — it handles the full lifecycle in a single call. Ideal for retroactively logging completed work.',
+        {
+            projectId: z.string().describe('Project ID to log work against — use list_projects if unknown.'),
+            title: z.string().describe('Title of the work done. Used first to search for an existing task — be specific enough to match if one exists.'),
+            summary: z.string().describe('Detailed description of what was accomplished. Supports markdown. Include: what changed, why, key decisions, and caveats.'),
+            priority: z.enum(['low', 'medium', 'high', 'urgent']).optional().default('medium').describe('Priority for the task if a new one must be created.'),
+            filesChanged: z.array(z.string()).optional().describe('List of files created or modified. Shown in the completion comment for traceability.'),
+            workspaceId: z.string().optional().describe('Workspace slug. Defaults to BRIORIGHT_WORKSPACE_ID.'),
+            apiKey: z.string().optional().describe('Brioright API key.')
+        },
+        async ({ projectId, title, summary, priority, filesChanged, workspaceId, apiKey }) => {
+            const ws = workspaceId || DEFAULT_WORKSPACE
+            if (!ws) throw new Error('workspaceId is required')
+
+            let taskId = null
+            let action = 'created'
+
+            // Step 1: Search for an existing open task with a similar title
+            try {
+                const searchQuery = title.substring(0, 60).trim()
+                const searchData = await call('GET', `/workspaces/${ws}/search?q=${encodeURIComponent(searchQuery)}`, null, apiKey)
+                const { tasks = [] } = searchData
+                // Find a task in the same project that isn't already closed
+                const match = tasks.find(t =>
+                    t.projectId === projectId &&
+                    !['done', 'cancelled'].includes(t.status)
+                )
+                if (match) {
+                    taskId = match.id
+                    action = 'found_existing'
+                }
+            } catch {
+                // Search failed — proceed to create a new task
+            }
+
+            // Step 2: Create task if no match was found
+            if (!taskId) {
+                const data = await call('POST', `/workspaces/${ws}/projects/${projectId}/tasks`, {
+                    title,
+                    description: summary,
+                    status: 'done',
+                    priority: priority || 'medium',
+                }, apiKey)
+                const task = data.task || data
+                taskId = task.id
+            } else {
+                // Mark the found task as done
+                await call('PATCH', `/workspaces/${ws}/tasks/${taskId}`, { status: 'done' }, apiKey)
+            }
+
+            // Step 3: Post structured completion comment
+            const fileSection = filesChanged?.length
+                ? `\n\n### 📁 Files Changed\n${filesChanged.map(f => `- \`${f}\``).join('\n')}`
+                : ''
+            const comment = [
+                `## ✅ Work Completed`,
+                ``,
+                summary,
+                fileSection,
+                ``,
+                `---`,
+                `_🤖 Auto-tracked by AI agent via \`track_work\` at ${new Date().toLocaleString()}_`
+            ].join('\n')
+
+            await call('POST', `/workspaces/${ws}/tasks/${taskId}/comments`, { text: comment }, apiKey)
+
+            const actionLabel = action === 'found_existing'
+                ? `♻️  Found existing open task — marked it done`
+                : `🆕 No matching task found — created a new one`
+
+            return { content: [{ type: 'text', text: `✅ Work tracked!\n\n${actionLabel}\nTask ID: ${taskId}\nCompletion summary posted as a comment.` }] }
+        }
+    )
+
     return server
 
 }

package/list-local-ws.js

@@ -0,0 +1,21 @@
+import axios from 'axios'
+import dotenv from 'dotenv'
+
+dotenv.config({ path: './.env' })
+
+async function listWorkspaces() {
+    const API_URL = process.env.BRIORIGHT_API_URL || 'http://localhost:3001/api'
+    const API_KEY = process.env.BRIORIGHT_API_KEY
+
+    try {
+        const res = await axios.get(`${API_URL}/workspaces`, {
+            headers: { 'X-API-Key': API_KEY }
+        })
+        console.log('Workspaces found on local server:')
+        console.log(JSON.stringify(res.data.workspaces || res.data, null, 2))
+    } catch (err) {
+        console.error('Error fetching workspaces:', err.message)
+    }
+}
+
+listWorkspaces()

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "brioright-mcp",
-    "version": "1.5.0",
+    "version": "1.7.0",
     "description": "MCP server for Brioright — lets AI assistants (Claude, Cursor, ChatGPT) create, search, analyse and manage tasks via natural language",
     "type": "module",
 

package/test-logic.js

@@ -0,0 +1,65 @@
+import axios from 'axios'
+import dotenv from 'dotenv'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+dotenv.config({ path: path.join(__dirname, '.env') })
+
+const API_URL = process.env.BRIORIGHT_API_URL || 'http://localhost:5000/api'
+const API_KEY = process.env.BRIORIGHT_API_KEY
+const WS_SLUG = process.env.BRIORIGHT_WORKSPACE_ID
+
+if (!API_KEY || !WS_SLUG) {
+    console.error('❌ BRIORIGHT_API_KEY and BRIORIGHT_WORKSPACE_ID must be set in .env')
+    process.exit(1)
+}
+
+const client = axios.create({
+    baseURL: API_URL,
+    headers: { 'X-API-Key': API_KEY }
+})
+
+async function testTools() {
+    console.log('🚀 Starting MCP Tool Verification...\n')
+
+    try {
+        // 1. Test Search Users
+        console.log('🔍 Testing: search_users ("Sanket")...')
+        const users = await client.get('/users/search?q=Sanket')
+        console.log(`✅ Found ${users.data.users?.length || 0} users.\n`)
+
+        // 2. Test Project Analytics
+        console.log('📊 Testing: get_project_analytics...')
+        const projects = await client.get(`/workspaces/${WS_SLUG}/projects`)
+        const projectId = projects.data.projects?.[0]?.id
+        if (projectId) {
+            const analytics = await client.get(`/workspaces/${WS_SLUG}/projects/${projectId}/analytics`)
+            console.log(`✅ Analytics fetched for project: ${projectId}\n`)
+        } else {
+            console.log('⚠️ No projects found to test analytics.\n')
+        }
+
+        // 3. Test Notifications
+        console.log('🔔 Testing: get_notifications...')
+        const notifications = await client.get('/notifications')
+        console.log(`✅ Fetched ${notifications.data.notifications?.length || 0} notifications.\n`)
+
+        // 4. Test Active Timers
+        console.log('⏱️ Testing: get_active_timers...')
+        const timers = await client.get(`/workspaces/${WS_SLUG}/time-entries/active`)
+        console.log(`✅ Fetched active timers.\n`)
+
+        console.log('🎉 All core endpoints for new tools verified!')
+    } catch (error) {
+        console.error('❌ Test failed:')
+        if (error.response) {
+            console.error(`   Status: ${error.response.status}`)
+            console.error(`   Data: ${JSON.stringify(error.response.data)}`)
+        } else {
+            console.error(`   Message: ${error.message}`)
+        }
+    }
+}
+
+testTools()