internaltool-mcp 1.0.0

package/README.md

@@ -0,0 +1,103 @@
+# internaltool-mcp
+
+MCP server for [InternalTool](https://github.com/your-org/internaltool) — connect AI assistants like **Claude Code** and **Cursor** directly to your project and task management platform.
+
+## Quick start
+
+### 1. Generate an API key
+
+In InternalTool, generate a personal API key:
+
+```bash
+curl -X POST https://your-server.com/api/auth/api-keys \
+  -H "Authorization: Bearer <your-jwt>" \
+  -H "Content-Type: application/json" \
+  -d '{"label": "Claude Code - MacBook"}'
+```
+
+Copy the `token` from the response — it starts with `ilt_` and is shown **once only**.
+
+### 2. Add to Claude Code
+
+```bash
+claude mcp add internaltool \
+  -e INTERNALTOOL_TOKEN=ilt_your_token_here \
+  -- npx -y internaltool-mcp --url https://your-server.com
+```
+
+### 3. Add to Cursor
+
+Create or edit `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "internaltool": {
+      "command": "npx",
+      "args": ["-y", "internaltool-mcp", "--url", "https://your-server.com"],
+      "env": {
+        "INTERNALTOOL_TOKEN": "ilt_your_token_here"
+      }
+    }
+  }
+}
+```
+
+That's it. No clone. No install. Just `npx`.
+
+---
+
+## CLI flags
+
+| Flag | Env var equivalent | Description |
+|---|---|---|
+| `--url <url>` | `INTERNALTOOL_URL` | Base URL of your InternalTool server |
+| `--token <token>` | `INTERNALTOOL_TOKEN` | Personal API key (`ilt_...`) — recommended |
+| `--email <email>` | `INTERNALTOOL_EMAIL` | Email (alternative to API key) |
+| `--password <pw>` | `INTERNALTOOL_PASSWORD` | Password (alternative to API key) |
+
+CLI flags take precedence over environment variables.
+
+---
+
+## Managing API keys
+
+```bash
+# List your keys (no raw tokens shown)
+GET /api/auth/api-keys
+
+# Generate a new key
+POST /api/auth/api-keys  { "label": "Cursor - Work Laptop" }
+
+# Revoke a key
+DELETE /api/auth/api-keys/:keyId
+```
+
+- Maximum **10 keys** per user
+- Keys show `lastUsedAt` so you know which ones are active
+- Revoke instantly — no session to wait for
+
+---
+
+## Available tools (25 total)
+
+| Category | Tools |
+|---|---|
+| Auth | `login`, `get_current_user` |
+| Users | `list_users` |
+| Projects | `list_projects`, `get_project`, `create_project`, `update_project`, `update_project_members`, `delete_project` |
+| Tasks | `create_task`, `get_task`, `update_task`, `move_task`, `delete_task`, `park_task`, `unpark_task` |
+| Issues | `create_task_issue`, `update_task_issue` |
+| Approval | `submit_task_for_approval`, `decide_task_approval` |
+| Comments | `list_task_comments`, `add_task_comment`, `get_task_activity` |
+| Notifications | `list_notifications`, `mark_all_notifications_read`, `delete_all_notifications` |
+| GitHub | `get_project_commits`, `get_project_branches` |
+| Admin | `admin_list_users`, `admin_get_analytics` |
+
+## Example prompts
+
+- *"List my projects"*
+- *"Create a task called 'Fix login bug' in HRMS with critical priority"*
+- *"Move task 683abc... to in_progress"*
+- *"What are my unread notifications?"*
+- *"Show me all comments on task 683abc..."*

package/api-client.js

@@ -0,0 +1,110 @@
+/**
+ * Lightweight HTTP client for InternalTool API.
+ *
+ * Auth priority:
+ *  1. INTERNALTOOL_TOKEN (ilt_...) — API key, no login needed
+ *  2. INTERNALTOOL_EMAIL + INTERNALTOOL_PASSWORD — auto-login with JWT
+ *  3. Manual login via the `login` tool
+ */
+
+export let BASE_URL = (process.env.INTERNALTOOL_URL || 'http://localhost:5001').replace(/\/$/, '')
+
+let apiToken = process.env.INTERNALTOOL_TOKEN || null   // ilt_... personal API key
+let accessToken = null
+let refreshToken = null
+
+/** Called from index.js after CLI args are parsed */
+export function configure({ url, token } = {}) {
+  if (url) BASE_URL = url.replace(/\/$/, '')
+  if (token) apiToken = token
+}
+
+function authHeader() {
+  if (apiToken) return `Bearer ${apiToken}`
+  if (accessToken) return `Bearer ${accessToken}`
+  return null
+}
+
+async function apiFetch(method, path, body, authenticated = true) {
+  const headers = { 'Content-Type': 'application/json' }
+
+  if (authenticated) {
+    const auth = authHeader()
+    if (!auth) {
+      // No API key and no JWT — try auto-login with env credentials
+      await autoLogin()
+    }
+    headers['Authorization'] = authHeader()
+  }
+
+  const res = await fetch(`${BASE_URL}${path}`, {
+    method,
+    headers,
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  })
+
+  // Only JWT tokens expire — API keys don't need refresh
+  if (res.status === 401 && !apiToken && authenticated && refreshToken) {
+    const refreshed = await tryRefresh()
+    if (refreshed) {
+      headers['Authorization'] = authHeader()
+      const retry = await fetch(`${BASE_URL}${path}`, {
+        method,
+        headers,
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+      })
+      return retry.json()
+    }
+  }
+
+  return res.json()
+}
+
+async function autoLogin() {
+  const email = process.env.INTERNALTOOL_EMAIL
+  const password = process.env.INTERNALTOOL_PASSWORD
+  if (!email || !password) {
+    throw new Error(
+      'Not authenticated. Set INTERNALTOOL_TOKEN (recommended) or INTERNALTOOL_EMAIL + INTERNALTOOL_PASSWORD, or call the "login" tool.'
+    )
+  }
+  await login(email, password)
+}
+
+export async function login(email, password) {
+  const res = await fetch(`${BASE_URL}/api/auth/login`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ email, password }),
+  })
+  const data = await res.json()
+  if (!data.success) throw new Error(data.message || 'Login failed')
+  accessToken = data.data.accessToken
+  refreshToken = data.data.refreshToken
+  return data.data
+}
+
+async function tryRefresh() {
+  try {
+    const res = await fetch(`${BASE_URL}/api/auth/refresh`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ refreshToken }),
+    })
+    const data = await res.json()
+    if (data.success) {
+      accessToken = data.data.accessToken
+      refreshToken = data.data.refreshToken
+      return true
+    }
+  } catch { /* fall through */ }
+  return false
+}
+
+export const api = {
+  get:    (path)       => apiFetch('GET',    path),
+  post:   (path, body) => apiFetch('POST',   path, body),
+  patch:  (path, body) => apiFetch('PATCH',  path, body),
+  delete: (path)       => apiFetch('DELETE', path),
+  isUsingApiKey: () => !!apiToken,
+}

package/index.js

@@ -0,0 +1,416 @@
+#!/usr/bin/env node
+/**
+ * InternalTool MCP Server
+ *
+ * Usage (API key — recommended):
+ *   npx internaltool-mcp --url https://your-server.com --token ilt_abc123...
+ *
+ * Usage (email/password):
+ *   npx internaltool-mcp --url https://your-server.com --email you@x.com --password secret
+ *
+ * Usage (env vars):
+ *   INTERNALTOOL_TOKEN=ilt_abc123 npx internaltool-mcp
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { z } from 'zod'
+import { api, login, configure, BASE_URL } from './api-client.js'
+
+// ── Parse CLI args ────────────────────────────────────────────────────────────
+// Supports: --url, --token, --email, --password
+const args = process.argv.slice(2)
+const getArg = (flag) => {
+  const i = args.indexOf(flag)
+  return i !== -1 && args[i + 1] ? args[i + 1] : null
+}
+
+const cliUrl      = getArg('--url')
+const cliToken    = getArg('--token')
+const cliEmail    = getArg('--email')
+const cliPassword = getArg('--password')
+
+// CLI args take precedence over env vars
+if (cliEmail)    process.env.INTERNALTOOL_EMAIL    = cliEmail
+if (cliPassword) process.env.INTERNALTOOL_PASSWORD = cliPassword
+
+configure({ url: cliUrl, token: cliToken })
+
+const server = new McpServer({
+  name: 'internaltool',
+  version: '1.0.0',
+})
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function text(value) {
+  const str = typeof value === 'string' ? value : JSON.stringify(value, null, 2)
+  return { content: [{ type: 'text', text: str }] }
+}
+
+function errorText(message) {
+  return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true }
+}
+
+async function call(fn) {
+  try {
+    const result = await fn()
+    if (result && result.success === false) {
+      return errorText(result.message || 'API returned an error')
+    }
+    return text(result.data !== undefined ? result.data : result)
+  } catch (e) {
+    return errorText(e.message)
+  }
+}
+
+// ─── Auth ────────────────────────────────────────────────────────────────────
+
+server.tool(
+  'login',
+  'Authenticate with the InternalTool API. Required before using other tools unless INTERNALTOOL_EMAIL and INTERNALTOOL_PASSWORD env vars are configured.',
+  {
+    email:    z.string().email().describe('User email address'),
+    password: z.string().describe('User password'),
+  },
+  async ({ email, password }) => {
+    try {
+      const data = await login(email, password)
+      return text({ message: 'Login successful', user: data.user })
+    } catch (e) {
+      return errorText(e.message)
+    }
+  }
+)
+
+server.tool(
+  'get_current_user',
+  'Get the currently authenticated user profile including name, email, and role.',
+  {},
+  async () => call(() => api.get('/api/auth/me'))
+)
+
+// ─── Users ───────────────────────────────────────────────────────────────────
+
+server.tool(
+  'list_users',
+  'List all users in the directory. Useful for finding user IDs when assigning tasks or adding project members.',
+  {
+    search: z.string().optional().describe('Filter users by name or email'),
+  },
+  async ({ search }) => {
+    const qs = search ? `?search=${encodeURIComponent(search)}` : ''
+    return call(() => api.get(`/api/users/directory${qs}`))
+  }
+)
+
+// ─── Projects ────────────────────────────────────────────────────────────────
+
+server.tool(
+  'list_projects',
+  'List all projects visible to the authenticated user with owner info and task counts.',
+  {},
+  async () => call(() => api.get('/api/projects'))
+)
+
+server.tool(
+  'get_project',
+  'Get full details of a project including members, GitHub integration settings, and ALL tasks on the board (all columns).',
+  {
+    projectId: z.string().describe("Project's MongoDB ObjectId"),
+  },
+  async ({ projectId }) => call(() => api.get(`/api/projects/${projectId}`))
+)
+
+server.tool(
+  'create_project',
+  'Create a new project. Only admins and members can create projects.',
+  {
+    name:                z.string().describe('Project name (required)'),
+    memberIds:           z.array(z.string()).optional().describe('Array of user IDs to add as initial members'),
+    githubRepoFullName:  z.string().optional().describe("GitHub repo in 'owner/repo' format, e.g. 'acme/backend'"),
+  },
+  async (args) => call(() => api.post('/api/projects', args))
+)
+
+server.tool(
+  'update_project',
+  'Update a project\'s GitHub integration settings (owner or admin only).',
+  {
+    projectId:            z.string().describe("Project's MongoDB ObjectId"),
+    githubRepoFullName:   z.string().optional().describe("GitHub repo in 'owner/repo' format. Pass empty string to unlink."),
+    githubDefaultBranch:  z.string().optional().describe("Default branch for merge-to-done automation (default: 'main')"),
+  },
+  async ({ projectId, ...fields }) => call(() => api.patch(`/api/projects/${projectId}`, fields))
+)
+
+server.tool(
+  'update_project_members',
+  'Replace the project member list. Owner is always preserved. Admin or project owner only.',
+  {
+    projectId:  z.string().describe("Project's MongoDB ObjectId"),
+    memberIds:  z.array(z.string()).describe('Array of user IDs that should be members (replaces current list)'),
+  },
+  async ({ projectId, memberIds }) =>
+    call(() => api.patch(`/api/projects/${projectId}/members`, { memberIds }))
+)
+
+server.tool(
+  'delete_project',
+  'Permanently delete a project and all its tasks, comments, and activity. Owner or admin only. Cannot be undone.',
+  {
+    projectId: z.string().describe("Project's MongoDB ObjectId"),
+  },
+  async ({ projectId }) => call(() => api.delete(`/api/projects/${projectId}`))
+)
+
+// ─── Tasks ───────────────────────────────────────────────────────────────────
+
+server.tool(
+  'get_task',
+  'Get full details of a task including title, description, column, priority, assignees, subtasks, issues, approval status, park note, and GitHub merge info.',
+  {
+    taskId: z.string().describe("Task's MongoDB ObjectId"),
+  },
+  async ({ taskId }) => call(() => api.get(`/api/tasks/${taskId}`))
+)
+
+server.tool(
+  'create_task',
+  'Create a new task in a project. Only the project owner or admin can create tasks.',
+  {
+    projectId:       z.string().describe("Project's MongoDB ObjectId"),
+    title:           z.string().describe('Task title (required)'),
+    description:     z.string().optional().describe('Short task description'),
+    readmeMarkdown:  z.string().optional().describe('Full markdown implementation plan for the task'),
+    priority:        z.enum(['low', 'medium', 'high', 'critical']).optional().describe('Priority level (default: medium)'),
+    column:          z.enum(['backlog', 'todo', 'in_progress', 'in_review', 'done']).optional().describe('Initial column (default: backlog)'),
+    assignees:       z.array(z.string()).optional().describe('Array of user IDs to assign'),
+  },
+  async ({ projectId, ...taskData }) =>
+    call(() => api.post(`/api/projects/${projectId}/tasks`, taskData))
+)
+
+server.tool(
+  'update_task',
+  'Update a task\'s fields. Assignee or project team member required. Cannot edit readmeMarkdown or subtasks while approval is pending.',
+  {
+    taskId:          z.string().describe("Task's MongoDB ObjectId"),
+    title:           z.string().optional().describe('New title'),
+    description:     z.string().optional().describe('New short description'),
+    readmeMarkdown:  z.string().optional().describe('Full markdown implementation plan (blocked during pending approval)'),
+    priority:        z.enum(['low', 'medium', 'high', 'critical']).optional().describe('New priority level'),
+    assignees:       z.array(z.string()).optional().describe('Array of user IDs — replaces current assignees (project members only)'),
+    subtasks:        z.array(z.object({
+      _id:   z.string().optional().describe('Existing subtask ID, or omit to create new'),
+      title: z.string(),
+      done:  z.boolean().optional(),
+      order: z.number().optional(),
+    })).optional().describe('Full replacement list of subtasks'),
+  },
+  async ({ taskId, ...fields }) => call(() => api.patch(`/api/tasks/${taskId}`, fields))
+)
+
+server.tool(
+  'move_task',
+  'Move a task to a different column on the kanban board. Moving from planning (backlog/todo) to execution columns requires an approved README plan. GitHub-linked projects block manual moves to "done".',
+  {
+    taskId:  z.string().describe("Task's MongoDB ObjectId"),
+    column:  z.enum(['backlog', 'todo', 'in_progress', 'in_review', 'done']).describe('Target column'),
+    toIndex: z.number().int().min(0).default(0).describe('Position in the column (0 = top)'),
+  },
+  async ({ taskId, column, toIndex }) =>
+    call(() => api.post(`/api/tasks/${taskId}/move`, { column, toIndex }))
+)
+
+server.tool(
+  'delete_task',
+  'Permanently delete a task and its comments, activity, and notifications. Project team member required. Cannot be undone.',
+  {
+    taskId: z.string().describe("Task's MongoDB ObjectId"),
+  },
+  async ({ taskId }) => call(() => api.delete(`/api/tasks/${taskId}`))
+)
+
+// ─── Park / Unpark ───────────────────────────────────────────────────────────
+
+server.tool(
+  'park_task',
+  'Park a task to temporarily pause it, capturing the current work context.',
+  {
+    taskId:    z.string().describe("Task's MongoDB ObjectId"),
+    summary:   z.string().optional().describe('Summary of work done so far (max 1000 chars)'),
+    remaining: z.string().optional().describe('What still needs to be done (max 1000 chars)'),
+    blockers:  z.string().optional().describe('What is blocking progress (max 500 chars)'),
+  },
+  async ({ taskId, summary = '', remaining = '', blockers = '' }) =>
+    call(() => api.patch(`/api/tasks/${taskId}/park`, { summary, remaining, blockers }))
+)
+
+server.tool(
+  'unpark_task',
+  'Unpark a previously parked task to resume work on it.',
+  {
+    taskId: z.string().describe("Task's MongoDB ObjectId"),
+  },
+  async ({ taskId }) => call(() => api.patch(`/api/tasks/${taskId}/unpark`, {}))
+)
+
+// ─── Issues ──────────────────────────────────────────────────────────────────
+
+server.tool(
+  'create_task_issue',
+  'Create a sub-issue/bug report under a task.',
+  {
+    taskId:      z.string().describe("Task's MongoDB ObjectId"),
+    title:       z.string().describe('Issue title'),
+    severity:    z.enum(['low', 'medium', 'high', 'critical']).optional().describe('Issue severity (default: medium)'),
+  },
+  async ({ taskId, title, severity }) =>
+    call(() => api.post(`/api/tasks/${taskId}/issues`, { title, severity }))
+)
+
+server.tool(
+  'update_task_issue',
+  'Update a sub-issue under a task (title, severity, or status).',
+  {
+    taskId:   z.string().describe("Task's MongoDB ObjectId"),
+    issueId:  z.string().describe("Issue's sub-document ID"),
+    title:    z.string().optional().describe('New issue title'),
+    severity: z.enum(['low', 'medium', 'high', 'critical']).optional().describe('New severity'),
+    status:   z.enum(['open', 'closed']).optional().describe('New status'),
+  },
+  async ({ taskId, issueId, ...fields }) =>
+    call(() => api.patch(`/api/tasks/${taskId}/issues/${issueId}`, fields))
+)
+
+// ─── Approval ────────────────────────────────────────────────────────────────
+
+server.tool(
+  'submit_task_for_approval',
+  'Submit a task\'s implementation plan (readmeMarkdown) for review. The README must be at least 50 characters.',
+  {
+    taskId:     z.string().describe("Task's MongoDB ObjectId"),
+    reviewerId: z.string().describe("User ID of the designated reviewer"),
+  },
+  async ({ taskId, reviewerId }) =>
+    call(() => api.post(`/api/tasks/${taskId}/approval/submit`, { reviewerId }))
+)
+
+server.tool(
+  'decide_task_approval',
+  'Approve or reject a task\'s implementation plan. Only the designated reviewer can call this.',
+  {
+    taskId:   z.string().describe("Task's MongoDB ObjectId"),
+    decision: z.enum(['approve', 'reject']).describe('Approval decision'),
+    note:     z.string().optional().describe('Optional note explaining the decision'),
+  },
+  async ({ taskId, decision, note }) =>
+    call(() => api.post(`/api/tasks/${taskId}/approval/decide`, { decision, note }))
+)
+
+// ─── Comments ────────────────────────────────────────────────────────────────
+
+server.tool(
+  'list_task_comments',
+  'List all comments on a task in chronological order.',
+  {
+    taskId: z.string().describe("Task's MongoDB ObjectId"),
+  },
+  async ({ taskId }) => call(() => api.get(`/api/tasks/${taskId}/comments`))
+)
+
+server.tool(
+  'add_task_comment',
+  'Add a markdown comment to a task. Mention users with @their@email.com to notify them.',
+  {
+    taskId: z.string().describe("Task's MongoDB ObjectId"),
+    body:   z.string().describe('Comment body in markdown. Use @email to mention users.'),
+  },
+  async ({ taskId, body }) =>
+    call(() => api.post(`/api/tasks/${taskId}/comments`, { body }))
+)
+
+// ─── Activity ────────────────────────────────────────────────────────────────
+
+server.tool(
+  'get_task_activity',
+  'Get the full activity/audit log for a task (last 100 events, newest first).',
+  {
+    taskId: z.string().describe("Task's MongoDB ObjectId"),
+  },
+  async ({ taskId }) => call(() => api.get(`/api/tasks/${taskId}/activity`))
+)
+
+// ─── Notifications ───────────────────────────────────────────────────────────
+
+server.tool(
+  'list_notifications',
+  'List recent notifications for the current user including unread count.',
+  {},
+  async () => call(() => api.get('/api/notifications'))
+)
+
+server.tool(
+  'mark_all_notifications_read',
+  'Mark all notifications as read.',
+  {},
+  async () => call(() => api.patch('/api/notifications/read-all', {}))
+)
+
+server.tool(
+  'delete_all_notifications',
+  'Clear/delete all notifications for the current user.',
+  {},
+  async () => call(() => api.delete('/api/notifications/clear'))
+)
+
+// ─── GitHub ──────────────────────────────────────────────────────────────────
+
+server.tool(
+  'get_project_commits',
+  'Get recent GitHub commits for a project. Requires the project to have a GitHub repo linked.',
+  {
+    projectId: z.string().describe("Project's MongoDB ObjectId"),
+    branch:    z.string().optional().describe('Branch name (defaults to project default branch)'),
+    perPage:   z.number().int().min(1).max(100).optional().describe('Number of commits to return (default: 20)'),
+  },
+  async ({ projectId, branch, perPage }) => {
+    const params = new URLSearchParams()
+    if (branch) params.set('sha', branch)
+    if (perPage) params.set('per_page', String(perPage))
+    const qs = params.toString() ? `?${params}` : ''
+    return call(() => api.get(`/api/projects/${projectId}/github/commits${qs}`))
+  }
+)
+
+server.tool(
+  'get_project_branches',
+  'Get GitHub branches for a project. Requires the project to have a GitHub repo linked.',
+  {
+    projectId: z.string().describe("Project's MongoDB ObjectId"),
+  },
+  async ({ projectId }) =>
+    call(() => api.get(`/api/projects/${projectId}/github/branches`))
+)
+
+// ─── Admin ───────────────────────────────────────────────────────────────────
+
+server.tool(
+  'admin_list_users',
+  'List all users in the system. Admin role required.',
+  {},
+  async () => call(() => api.get('/api/admin/users'))
+)
+
+server.tool(
+  'admin_get_analytics',
+  'Get platform-wide analytics. Admin role required.',
+  {},
+  async () => call(() => api.get('/api/admin/analytics'))
+)
+
+// ─── Start ───────────────────────────────────────────────────────────────────
+
+const transport = new StdioServerTransport()
+await server.connect(transport)

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "internaltool-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for InternalTool — connect AI assistants (Claude Code, Cursor) to your project and task management platform",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "internaltool-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "api-client.js",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node index.js",
+    "dev": "node --watch index.js",
+    "prepublishOnly": "node --check index.js && node --check api-client.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "internaltool",
+    "project-management",
+    "claude",
+    "cursor",
+    "ai"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  }
+}