@locusai/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Locus AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@locusai/mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.25.2",
+    "zod": "^3.23.8",
+    "@locusai/shared": "workspace:*"
+  }
+}

package/src/api.ts

@@ -0,0 +1,45 @@
+import { API_BASE } from "./config.js";
+import type { ToolResult } from "./types.js";
+
+export function success(data: unknown): ToolResult {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+  };
+}
+
+export function error(message: string): ToolResult {
+  return {
+    content: [{ type: "text", text: `Error: ${message}` }],
+    isError: true,
+  };
+}
+
+export async function apiGet<T>(path: string): Promise<T> {
+  const res = await fetch(`${API_BASE}${path}`);
+  return res.json();
+}
+
+export async function apiPost<T>(
+  path: string,
+  body: Record<string, unknown>
+): Promise<{ data: T; status: number; ok: boolean }> {
+  const res = await fetch(`${API_BASE}${path}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const data = await res.json();
+  return { data, status: res.status, ok: res.ok };
+}
+
+export async function apiPatch<T>(
+  path: string,
+  body: Record<string, unknown>
+): Promise<T> {
+  const res = await fetch(`${API_BASE}${path}`, {
+    method: "PATCH",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  return res.json();
+}

package/src/config.ts

@@ -0,0 +1,18 @@
+import { parseArgs } from "node:util";
+
+const { values } = parseArgs({
+  args: Bun.argv,
+  options: {
+    project: { type: "string" },
+  },
+  strict: true,
+  allowPositionals: true,
+});
+
+if (!values.project) {
+  console.error("Usage: bun run mcp -- --project <workspaceDir>");
+  process.exit(1);
+}
+
+export const projectDir = values.project;
+export const API_BASE = "http://localhost:3080/api";

package/src/index.ts

@@ -0,0 +1,38 @@
+#!/usr/bin/env bun
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// Import config to trigger CLI arg parsing
+import "./config.js";
+
+// Import tool registration functions
+import { registerArtifactTools } from "./tools/artifacts.js";
+import { registerCiTools } from "./tools/ci.js";
+import { registerDocsTools } from "./tools/docs.js";
+import { registerKanbanTools } from "./tools/kanban.js";
+
+// Create server instance
+const server = new McpServer({
+  name: "locus",
+  version: "0.1.0",
+});
+
+// Register all tools
+registerDocsTools(server);
+registerKanbanTools(server);
+registerArtifactTools(server);
+registerCiTools(server);
+
+// Start the server
+async function main() {
+  try {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Locus MCP server running on stdio");
+  } catch (error) {
+    console.error("Failed to start MCP server:", error);
+    process.exit(1);
+  }
+}
+
+main();

package/src/tools/artifacts.ts

@@ -0,0 +1,40 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { apiGet, error, success } from "../api.js";
+
+export function registerArtifactTools(server: McpServer): void {
+  server.registerTool(
+    "artifacts.list",
+    {
+      title: "List Artifacts",
+      description:
+        "List all artifacts for a task (including implementation drafts)",
+      inputSchema: { taskId: z.number() },
+    },
+    async ({ taskId }) => {
+      try {
+        const data = await apiGet(`/artifacts?taskId=${taskId}`);
+        return success(data);
+      } catch (e) {
+        return error(String(e));
+      }
+    }
+  );
+
+  server.registerTool(
+    "artifacts.get",
+    {
+      title: "Get Artifact",
+      description: "Get the content of a specific artifact by ID",
+      inputSchema: { artifactId: z.number() },
+    },
+    async ({ artifactId }) => {
+      try {
+        const data = await apiGet(`/artifacts/${artifactId}`);
+        return success(data);
+      } catch (e) {
+        return error(String(e));
+      }
+    }
+  );
+}

package/src/tools/ci.ts

@@ -0,0 +1,25 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { apiPost, error, success } from "../api.js";
+
+export function registerCiTools(server: McpServer): void {
+  server.registerTool(
+    "ci.run",
+    {
+      title: "Run CI",
+      description: "Run a CI preset (e.g., 'quick' or 'full') for a task",
+      inputSchema: {
+        taskId: z.number(),
+        preset: z.string(),
+      },
+    },
+    async ({ taskId, preset }) => {
+      try {
+        const { data } = await apiPost("/ci/run", { taskId, preset });
+        return success(data);
+      } catch (e) {
+        return error(String(e));
+      }
+    }
+  );
+}

package/src/tools/docs.ts

@@ -0,0 +1,61 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { apiGet, apiPost, error, success } from "../api.js";
+
+export function registerDocsTools(server: McpServer): void {
+  server.registerTool(
+    "docs.tree",
+    {
+      title: "Documentation Tree",
+      description: "Get the documentation tree structure",
+      inputSchema: {},
+    },
+    async () => {
+      try {
+        const data = await apiGet("/docs/tree");
+        return success(data);
+      } catch (e) {
+        return error(String(e));
+      }
+    }
+  );
+
+  server.registerTool(
+    "docs.read",
+    {
+      title: "Read Document",
+      description: "Read a document from the documentation",
+      inputSchema: { path: z.string() },
+    },
+    async ({ path }) => {
+      try {
+        const data = await apiGet(
+          `/docs/read?path=${encodeURIComponent(path)}`
+        );
+        return success(data);
+      } catch (e) {
+        return error(String(e));
+      }
+    }
+  );
+
+  server.registerTool(
+    "docs.write",
+    {
+      title: "Write Document",
+      description: "Write content to a document",
+      inputSchema: {
+        path: z.string(),
+        content: z.string(),
+      },
+    },
+    async ({ path, content }) => {
+      try {
+        const { data } = await apiPost("/docs/write", { path, content });
+        return success(data);
+      } catch (e) {
+        return error(String(e));
+      }
+    }
+  );
+}

package/src/tools/kanban.ts

@@ -0,0 +1,298 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { apiGet, apiPatch, apiPost, error, success } from "../api.js";
+import { projectDir } from "../config.js";
+import { ROLE_PROMPTS, type Sprint, type Task } from "../types.js";
+
+export function registerKanbanTools(server: McpServer): void {
+  // View active sprint tasks
+  server.registerTool(
+    "kanban.sprint",
+    {
+      title: "View Active Sprint",
+      description:
+        "View all tasks in the active sprint with their status. Use this to see sprint progress. To claim a task to work on, use kanban.next instead.",
+      inputSchema: {},
+    },
+    async () => {
+      try {
+        const sprints = await apiGet<Sprint[]>("/sprints");
+        const activeSprint = sprints.find((s) => s.status === "ACTIVE");
+
+        if (!activeSprint) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: JSON.stringify(
+                  {
+                    error: "NO_ACTIVE_SPRINT",
+                    message:
+                      "No active sprint found. Please start a sprint from the Backlog before requesting tasks.",
+                  },
+                  null,
+                  2
+                ),
+              },
+            ],
+            isError: true,
+          };
+        }
+
+        // Get tasks for this sprint
+        const tasks = await apiGet<Task[]>(
+          `/tasks?sprintId=${activeSprint.id}`
+        );
+
+        return success({
+          sprint: { id: activeSprint.id, name: activeSprint.name },
+          tasks: tasks.map((t) => ({
+            id: t.id,
+            title: t.title,
+            status: t.status,
+            priority: t.priority,
+            assigneeRole: t.assigneeRole,
+          })),
+          hint: "Use kanban.next to claim and start working on the next available task.",
+        });
+      } catch (e) {
+        return error(String(e));
+      }
+    }
+  );
+
+  // Priority queue - get next task to work on from active sprint
+  server.registerTool(
+    "kanban.next",
+    {
+      title: "Get & Claim Next Task",
+      description:
+        "START HERE: Get and claim the next highest priority task from the active sprint. This is the PRIMARY way to get a task to work on. The task is automatically assigned to you. Returns full task details including acceptance criteria.",
+      inputSchema: {
+        workerId: z.string().optional(),
+      },
+    },
+    async ({ workerId }) => {
+      try {
+        // First, check if there's an active sprint
+        const sprints = await apiGet<Sprint[]>("/sprints");
+        const activeSprint = sprints.find((s) => s.status === "ACTIVE");
+
+        if (!activeSprint) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: JSON.stringify(
+                  {
+                    error: "NO_ACTIVE_SPRINT",
+                    message:
+                      "No active sprint found. Please start a sprint from the Backlog before requesting tasks.",
+                  },
+                  null,
+                  2
+                ),
+              },
+            ],
+            isError: true,
+          };
+        }
+
+        // Dispatch task from the active sprint
+        const {
+          data: task,
+          status,
+          ok,
+        } = await apiPost<Task>("/tasks/dispatch", {
+          workerId,
+          sprintId: String(activeSprint.id),
+        });
+
+        if (status === 404) {
+          return success({
+            message: `No tasks available in active sprint "${activeSprint.name}"`,
+            sprintId: activeSprint.id,
+            sprintName: activeSprint.name,
+          });
+        }
+
+        if (!ok) {
+          throw new Error("Failed to dispatch task");
+        }
+
+        // Inject system prompts
+        const systemInstructions =
+          task.assigneeRole && ROLE_PROMPTS[task.assigneeRole];
+
+        return success({
+          message: "Assigned task",
+          sprint: { id: activeSprint.id, name: activeSprint.name },
+          task: { ...task, systemInstructions },
+        });
+      } catch (e) {
+        return error(String(e));
+      }
+    }
+  );
+
+  // Get specific task details
+  server.registerTool(
+    "kanban.get",
+    {
+      title: "Get Task Details",
+      description:
+        "Get full details of a task you already know the ID for. Use kanban.next to claim a new task instead of this.",
+      inputSchema: { taskId: z.number() },
+    },
+    async ({ taskId }) => {
+      try {
+        const data = await apiGet<Task>(`/tasks/${taskId}`);
+        const systemInstructions =
+          data.assigneeRole && ROLE_PROMPTS[data.assigneeRole];
+        return success({ ...data, systemInstructions });
+      } catch (e) {
+        return error(String(e));
+      }
+    }
+  );
+
+  // Move task status
+  server.registerTool(
+    "kanban.move",
+    {
+      title: "Move Task Status",
+      description:
+        "Update task status. When work is complete, move to VERIFICATION (NOT DONE). Valid statuses: IN_PROGRESS, VERIFICATION. The DONE status is reserved for manual approval only.",
+      inputSchema: {
+        taskId: z.number(),
+        status: z.string(),
+      },
+    },
+    async ({ taskId, status }) => {
+      try {
+        const data = await apiPatch(`/tasks/${taskId}`, { status });
+        return success(data);
+      } catch (e) {
+        return error(String(e));
+      }
+    }
+  );
+
+  // Commit changes
+  server.registerTool(
+    "kanban.commit",
+    {
+      title: "Commit Task Changes",
+      description:
+        "Create a git commit with the task ID in the message. Call this BEFORE moving to VERIFICATION to save your work.",
+      inputSchema: {
+        taskId: z.number(),
+        additionalMessage: z.string().optional(),
+      },
+    },
+    async ({ taskId, additionalMessage }) => {
+      try {
+        const task = await apiGet<Task>(`/tasks/${taskId}`);
+
+        if (!task.title) {
+          return error("Task not found");
+        }
+
+        // Build commit message
+        let commitMessage = `Task #${taskId}: ${task.title}`;
+        if (additionalMessage) {
+          commitMessage += `\n\n${additionalMessage}`;
+        }
+
+        // Execute git commands
+        const addProc = Bun.spawn(["git", "add", "-A"], {
+          cwd: projectDir,
+          stdout: "pipe",
+          stderr: "pipe",
+        });
+        await addProc.exited;
+
+        const commitProc = Bun.spawn(["git", "commit", "-m", commitMessage], {
+          cwd: projectDir,
+          stdout: "pipe",
+          stderr: "pipe",
+        });
+        const exitCode = await commitProc.exited;
+        const stdout = await new Response(commitProc.stdout).text();
+        const stderr = await new Response(commitProc.stderr).text();
+
+        if (exitCode !== 0) {
+          return success({
+            success: false,
+            error: stderr || "Git commit failed",
+            hint: "Make sure there are staged changes to commit",
+          });
+        }
+
+        return success({
+          success: true,
+          message: `Committed changes for Task #${taskId}`,
+          commitMessage,
+          output: stdout,
+        });
+      } catch (e) {
+        return error(String(e));
+      }
+    }
+  );
+
+  // Check acceptance criteria
+  server.registerTool(
+    "kanban.check",
+    {
+      title: "Check Acceptance Item",
+      description:
+        "Mark acceptance checklist items as completed. Pass the full updated checklist array with completed items marked.",
+      inputSchema: {
+        taskId: z.number(),
+        acceptanceChecklist: z.array(
+          z.object({
+            id: z.string(),
+            text: z.string(),
+            done: z.boolean(),
+          })
+        ),
+      },
+    },
+    async ({ taskId, acceptanceChecklist }) => {
+      try {
+        const data = await apiPatch(`/tasks/${taskId}`, {
+          acceptanceChecklist,
+        });
+        return success(data);
+      } catch (e) {
+        return error(String(e));
+      }
+    }
+  );
+
+  // Add comment
+  server.registerTool(
+    "kanban.comment",
+    {
+      title: "Add Comment",
+      description: "Add a comment to a task",
+      inputSchema: {
+        taskId: z.number(),
+        author: z.string(),
+        text: z.string(),
+      },
+    },
+    async ({ taskId, author, text }) => {
+      try {
+        const { data } = await apiPost(`/tasks/${taskId}/comment`, {
+          author,
+          text,
+        });
+        return success(data);
+      } catch (e) {
+        return error(String(e));
+      }
+    }
+  );
+}

package/src/types.ts

@@ -0,0 +1,68 @@
+export interface ToolResult {
+  [key: string]: unknown;
+  content: Array<{ type: "text"; text: string }>;
+  isError?: boolean;
+}
+
+export interface Task {
+  id: number;
+  title: string;
+  description?: string;
+  status: string;
+  priority: string;
+  assigneeRole?: string;
+  acceptanceChecklist?: Array<{
+    id: string;
+    text: string;
+    done: boolean;
+  }>;
+}
+
+export interface Sprint {
+  id: number;
+  name: string;
+  status: string;
+}
+
+export const ROLE_PROMPTS: Record<string, string> = {
+  FRONTEND: `## Frontend Implementation Guidelines
+
+### Design & Aesthetics
+- **Visual Excellence**: Create stunning, premium interfaces. Use vibrant colors, glassmorphism, and smooth animations. Avoid generic or flat designs.
+- **Modern Typography**: Use curated fonts (e.g., Inter, Roboto, Outfit). Avoid browser defaults.
+- **Dynamic Interactions**: Add hover effects, micro-animations, and fluid transitions to make the UI feel alive.
+- **Responsiveness**: Ensure flawless rendering across all device sizes.
+
+### Technical Standards
+- **Component-Driven**: Build small, reusable components. Use props for customization.
+- **State Management**: Keep state local where possible; use global state only when necessary.
+- **Clean Code**: Use semantic HTML, proper naming, and avoid inline styles (use CSS classes/variables).
+- **Performance**: Optimize images and minimize re-renders.
+
+### Workflow Rules (CRITICAL)
+1. **Branching**: A git branch is automatically created when task moves to IN_PROGRESS.
+2. **Working**: Implement the task, check all acceptance criteria in the task.
+3. **Committing**: Use \`kanban.commit\` when work is ready to save your changes.
+4. **Completion**: Move task to **VERIFICATION** using \`kanban.move(taskId, "VERIFICATION")\`.
+5. **NEVER move to DONE**: The system will reject direct DONE transitions. Only the manager can approve to DONE.
+6. **If Rejected**: Check task comments for feedback, fix issues, commit again, and move back to VERIFICATION.`,
+
+  BACKEND: `## Backend Implementation Guidelines
+
+### Architecture & Quality
+- **Modularity**: Keep concerns separated (routes, controllers, services, db).
+- **Type Safety**: Use strict TypeScript types. Avoid \`any\`.
+- **Error Handling**: Gracefully handle errors and return standard HTTP status codes.
+
+### Security & Performance
+- **Input Validation**: Validate all incoming data (zod/joi).
+- **Efficiency**: Optimize database queries and avoid N+1 problems.
+
+### Workflow Rules (CRITICAL)
+1. **Branching**: A git branch is automatically created when task moves to IN_PROGRESS.
+2. **Working**: Implement the task, check all acceptance criteria in the task.
+3. **Committing**: Use \`kanban.commit\` when work is ready to save your changes.
+4. **Completion**: Move task to **VERIFICATION** using \`kanban.move(taskId, "VERIFICATION")\`.
+5. **NEVER move to DONE**: The system will reject direct DONE transitions. Only the manager can approve to DONE.
+6. **If Rejected**: Check task comments for feedback, fix issues, commit again, and move back to VERIFICATION.`,
+};

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}