@mtaap/mcp 0.1.0

package/README.md

@@ -0,0 +1,139 @@
+# MTAAP MCP Server
+
+Standalone MCP server for managing tasks, projects, and git integration.
+
+## Installation
+
+```bash
+# Install globally
+npm install -g @mtaap/mcp
+
+# Or run directly
+npx @mtaap/mcp
+```
+
+## Configuration
+
+### Required Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `MTAAP_API_KEY` | Your MTAAP API key. Generate one at https://app.mtaap.io/settings/api-keys |
+
+### Optional Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `GITHUB_TOKEN` | GitHub personal access token for branch creation and PR features |
+
+### Example
+
+```bash
+export MTAAP_API_KEY=usr_xxxxx...
+export GITHUB_TOKEN=ghp_xxxxx...  # Optional, for git operations
+```
+
+## Available Tools
+
+### list_projects
+List accessible projects (personal + team via tags).
+
+### list_tasks
+Returns available tasks (filterable by project, state).
+
+### get_task
+Full task details including acceptance criteria.
+
+### assign_task
+Atomic claim → creates branch. Fails if already taken.
+
+### update_progress
+Reports status, updates checkboxes, writes checkpoint.
+
+### complete_task
+Marks complete, triggers PR, deletes local state file.
+
+### check_active_task
+Check for resumable task in `.mtaap/active-task.json`.
+
+### report_error
+Report unrecoverable error, displays on task in webapp.
+
+### get_project_context
+Returns assembled context (README, stack, conventions).
+
+### add_note
+Append implementation notes to task.
+
+### abandon_task
+Unassign self, cleanup branch, return to ready state.
+
+### create_personal_project
+Create project in user's personal workspace.
+
+## Usage
+
+1. Configure your environment variables
+2. Add to your MCP client configuration (Claude Desktop, OpenCode, etc.):
+
+```json
+{
+  "mcpServers": {
+    "mtaap": {
+      "command": "npx",
+      "args": ["@mtaap/mcp"],
+      "env": {
+        "MTAAP_BASE_URL": "https://app.mtaap.io",
+        "MTAAP_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+3. Use the tools from your AI agent
+
+## Development
+
+```bash
+# Build
+pnpm build
+
+# Watch mode
+pnpm dev
+
+# Run locally
+MTAAP_API_KEY=your-key pnpm start
+```
+
+## Troubleshooting
+
+### "MTAAP_API_KEY is required"
+
+You need to set the `MTAAP_API_KEY` environment variable. Generate an API key at https://app.mtaap.io/settings/api-keys
+
+### "GITHUB_TOKEN is not set" warning
+
+This warning appears when `GITHUB_TOKEN` is not configured. Git operations (branch creation, PR creation) require this token. The server will still start, but git-related features will fail.
+
+### "Invalid API key"
+
+Your API key may be expired or revoked. Generate a new one at https://app.mtaap.io/settings/api-keys
+
+### Connection issues
+
+Ensure your firewall allows outbound connections to your MTAAP instance. By default, the server connects to `https://app.mtaap.io`.
+
+## Publishing
+
+This package is published as `@mtaap/mcp` to npm.
+
+```bash
+# Build and publish
+pnpm build
+npm publish
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import { createMCPServer } from "./index.js";
+/**
+ * CLI entry point for the MTAAP MCP server.
+ * Validates environment, starts the server, and handles graceful shutdown.
+ */
+function validateEnvironment() {
+    const errors = [];
+    const warnings = [];
+    // Required: MTAAP_API_KEY
+    if (!process.env.MTAAP_API_KEY) {
+        errors.push("MTAAP_API_KEY is required. Generate one at https://app.mtaap.io/settings/api-keys");
+    }
+    // Optional but recommended: GITHUB_TOKEN
+    if (!process.env.GITHUB_TOKEN) {
+        warnings.push("GITHUB_TOKEN is not set. Branch creation and PR features will not work.");
+    }
+    // Print warnings
+    for (const warning of warnings) {
+        console.error(`[mtaap-mcp] Warning: ${warning}`);
+    }
+    // Exit if there are errors
+    if (errors.length > 0) {
+        for (const error of errors) {
+            console.error(`[mtaap-mcp] Error: ${error}`);
+        }
+        console.error("\nRequired environment variables:");
+        console.error("  MTAAP_API_KEY    Your MTAAP API key");
+        console.error("\nOptional environment variables:");
+        console.error("  GITHUB_TOKEN     GitHub personal access token for git operations");
+        process.exit(1);
+    }
+}
+async function main() {
+    console.error("[mtaap-mcp] Starting MTAAP MCP server...");
+    validateEnvironment();
+    try {
+        await createMCPServer();
+        console.error("[mtaap-mcp] Server started successfully");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`[mtaap-mcp] Failed to start server: ${message}`);
+        process.exit(1);
+    }
+}
+// Graceful shutdown handling
+function setupShutdownHandlers() {
+    const shutdown = (signal) => {
+        console.error(`[mtaap-mcp] Received ${signal}, shutting down...`);
+        process.exit(0);
+    };
+    process.on("SIGINT", () => shutdown("SIGINT"));
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+    // Handle uncaught exceptions
+    process.on("uncaughtException", (error) => {
+        console.error("[mtaap-mcp] Uncaught exception:", error.message);
+        process.exit(1);
+    });
+    // Handle unhandled promise rejections
+    process.on("unhandledRejection", (reason) => {
+        const message = reason instanceof Error ? reason.message : String(reason);
+        console.error("[mtaap-mcp] Unhandled rejection:", message);
+        process.exit(1);
+    });
+}
+setupShutdownHandlers();
+main();

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export declare function createMCPServer(): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA+IA,wBAAsB,eAAe,kBAiZpC"}

package/dist/index.js

@@ -0,0 +1,864 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { validateApiKey } from "@mtaap/auth";
+import { prisma } from "@mtaap/db";
+import { TaskState, ProjectType, ProjectOrigin, VERSION, } from "@mtaap/core";
+import { ApiKeyPermission } from "@mtaap/core";
+import { GitHubProvider } from "@mtaap/git";
+import { assertApiKeyPermission } from "./permissions.js";
+import { ListProjectsInputSchema, ListTasksInputSchema, GetTaskInputSchema, AssignTaskInputSchema, UpdateProgressInputSchema, CompleteTaskInputSchema, ReportErrorInputSchema, GetProjectContextInputSchema, AddNoteInputSchema, AbandonTaskInputSchema, CreatePersonalProjectInputSchema, } from "@mtaap/core";
+async function getAuthenticatedUser(apiKey) {
+    const result = await validateApiKey(apiKey);
+    if (!result) {
+        throw new Error("Invalid API key");
+    }
+    return {
+        userId: result.user.id,
+        organizationId: result.organization?.id,
+        apiKey: result.apiKey,
+    };
+}
+async function ensureAccessControl(projectId, userId, organizationId) {
+    if (!organizationId) {
+        const project = await prisma.project.findUnique({
+            where: { id: projectId },
+            include: { owner: true },
+        });
+        if (project?.ownerId !== userId) {
+            throw new Error("Access denied: You do not have permission to access this project");
+        }
+    }
+    else {
+        const project = await prisma.project.findUnique({
+            where: { id: projectId },
+            include: { organization: true },
+        });
+        if (!project || project.organizationId !== organizationId) {
+            throw new Error("Access denied: You do not have permission to access this project");
+        }
+        const userTags = await prisma.userTag.findMany({
+            where: { userId },
+            include: { tag: true },
+        });
+        const projectTags = await prisma.projectTag.findMany({
+            where: { projectId },
+            include: { tag: true },
+        });
+        const userTagNames = new Set(userTags.map((ut) => ut.tag.name));
+        const projectTagNames = new Set(projectTags.map((pt) => pt.tag.name));
+        const hasAccess = [...userTagNames].some((tag) => projectTagNames.has(tag));
+        if (!hasAccess) {
+            throw new Error("Access denied: Your tags do not grant access to this project");
+        }
+    }
+}
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+async function verifyPersonalAccess(projectId, userId) {
+    const project = await prisma.project.findUnique({
+        where: { id: projectId },
+        include: {
+            collaborators: {
+                where: { userId },
+            },
+        },
+    });
+    if (!project) {
+        throw new Error("Project not found");
+    }
+    const isOwner = project.ownerId === userId;
+    const isCollaborator = project.collaborators.length > 0;
+    if (!isOwner && !isCollaborator) {
+        throw new Error("Access denied: You do not have permission to access this project");
+    }
+}
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+function getGitHubClient(_organizationId) {
+    const githubToken = process.env.GITHUB_TOKEN;
+    if (!githubToken) {
+        throw new Error("GitHub token not configured");
+    }
+    return new GitHubProvider(githubToken);
+}
+function slugify(text, maxLength = 50) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .substring(0, maxLength);
+}
+export async function createMCPServer() {
+    const server = new McpServer({
+        name: "mtaap",
+        version: VERSION,
+    });
+    const apiKey = process.env.MTAAP_API_KEY;
+    if (!apiKey) {
+        throw new Error("MTAAP_API_KEY environment variable is required");
+    }
+    const auth = await getAuthenticatedUser(apiKey);
+    server.registerTool("list_projects", {
+        description: "List accessible projects (personal + team via tags)",
+    }, async (args) => {
+        assertApiKeyPermission(auth.apiKey, ApiKeyPermission.READ, "list_projects");
+        const validated = ListProjectsInputSchema.parse(args);
+        const projects = await listProjects(auth.userId, auth.organizationId, validated.workspaceType);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(projects, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("list_tasks", {
+        description: "Returns available tasks (filterable by project, state)",
+    }, async (args) => {
+        assertApiKeyPermission(auth.apiKey, ApiKeyPermission.READ, "list_tasks");
+        const validated = ListTasksInputSchema.parse(args);
+        if (validated.projectId) {
+            await ensureAccessControl(validated.projectId, auth.userId, auth.organizationId);
+        }
+        const tasks = await listTasks(auth.userId, auth.organizationId, validated.projectId, validated.state, validated.assigneeId);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(tasks, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("get_task", {
+        description: "Full task details including acceptance criteria",
+    }, async (args) => {
+        assertApiKeyPermission(auth.apiKey, ApiKeyPermission.READ, "get_task");
+        const validated = GetTaskInputSchema.parse(args);
+        const task = await getTaskWithChecks(validated.taskId, auth.userId, auth.organizationId);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(task, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("assign_task", {
+        description: "Atomic claim → creates branch. Fails if already taken.",
+    }, async (args) => {
+        assertApiKeyPermission(auth.apiKey, ApiKeyPermission.WRITE, "assign_task");
+        const validated = AssignTaskInputSchema.parse(args);
+        const result = await assignTask(validated.projectId, validated.taskId, auth.userId, auth.organizationId, validated.expectedState);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("update_progress", {
+        description: "Reports status, updates checkboxes, writes checkpoint",
+    }, async (args) => {
+        assertApiKeyPermission(auth.apiKey, ApiKeyPermission.WRITE, "update_progress");
+        const validated = UpdateProgressInputSchema.parse(args);
+        const result = await updateProgress(validated.taskId, auth.userId, validated.statusMessage, validated.completedCheckpointIds, validated.currentCheckpointIndex);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("complete_task", {
+        description: "Marks complete, triggers PR, deletes local state file",
+    }, async (args) => {
+        assertApiKeyPermission(auth.apiKey, ApiKeyPermission.WRITE, "complete_task");
+        const validated = CompleteTaskInputSchema.parse(args);
+        const result = await completeTask(validated.projectId, validated.taskId, auth.userId, auth.organizationId, validated.pullRequestTitle, validated.pullRequestBody);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("check_active_task", {
+        description: "Check for resumable task in .mtaap/active-task.json",
+    }, async () => {
+        assertApiKeyPermission(auth.apiKey, ApiKeyPermission.READ, "check_active_task");
+        const result = await checkActiveTask();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("report_error", {
+        description: "Report unrecoverable error, displays on task in webapp",
+    }, async (args) => {
+        assertApiKeyPermission(auth.apiKey, ApiKeyPermission.WRITE, "report_error");
+        const validated = ReportErrorInputSchema.parse(args);
+        const result = await reportTaskError(validated.taskId, auth.userId, validated.errorType, validated.errorMessage, validated.context);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("get_project_context", {
+        description: "Returns assembled context (README, stack, conventions)",
+    }, async (args) => {
+        assertApiKeyPermission(auth.apiKey, ApiKeyPermission.READ, "get_project_context");
+        const validated = GetProjectContextInputSchema.parse(args);
+        await ensureAccessControl(validated.projectId, auth.userId, auth.organizationId);
+        const context = await getProjectContext(validated.projectId);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(context, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("add_note", {
+        description: "Append implementation notes to task",
+    }, async (args) => {
+        assertApiKeyPermission(auth.apiKey, ApiKeyPermission.WRITE, "add_note");
+        const validated = AddNoteInputSchema.parse(args);
+        const result = await addTaskNote(validated.taskId, auth.userId, validated.content);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("abandon_task", {
+        description: "Unassign from a task and optionally delete the branch",
+    }, async (args) => {
+        assertApiKeyPermission(auth.apiKey, ApiKeyPermission.WRITE, "abandon_task");
+        const validated = AbandonTaskInputSchema.parse(args);
+        // Validate project access
+        await ensureAccessControl(validated.projectId, auth.userId, auth.organizationId || null);
+        const result = await abandonTask(validated.taskId, validated.projectId, auth.userId, validated.deleteBranch);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("create_personal_project", {
+        description: "Create project in user's personal workspace",
+    }, async (args) => {
+        assertApiKeyPermission(auth.apiKey, ApiKeyPermission.WRITE, "create_personal_project");
+        const validated = CreatePersonalProjectInputSchema.parse(args);
+        const result = await createPersonalProject(auth.userId, validated.name, validated.description, validated.repositoryUrl);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("get_version", {
+        description: "Get the current MTAAP version",
+    }, async () => {
+        assertApiKeyPermission(auth.apiKey, ApiKeyPermission.READ, "get_version");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        version: VERSION,
+                        timestamp: new Date().toISOString(),
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+async function listProjects(userId, organizationId, workspaceType = "ALL") {
+    const where = {};
+    const include = {};
+    if (workspaceType === "PERSONAL" || workspaceType === "ALL") {
+        where.ownerId = userId;
+        include.owner = true;
+    }
+    if (organizationId && (workspaceType === "TEAM" || workspaceType === "ALL")) {
+        where.OR = [
+            { organizationId },
+            { type: ProjectType.PERSONAL, ownerId: userId },
+        ];
+        include.organization = true;
+        include.projectTags = {
+            include: { tag: true },
+        };
+    }
+    const projects = await prisma.project.findMany({
+        where,
+        include,
+        orderBy: { updatedAt: "desc" },
+    });
+    const formattedProjects = projects.map((project) => ({
+        id: project.id,
+        name: project.name,
+        description: project.description,
+        type: project.type,
+        origin: project.origin,
+        repositoryUrl: project.repositoryUrl,
+        baseBranch: project.baseBranch,
+        tags: project.projectTags?.map((pt) => pt.tag.name) || [],
+        createdAt: project.createdAt,
+        updatedAt: project.updatedAt,
+    }));
+    return formattedProjects;
+}
+async function listTasks(userId, organizationId, projectId, state, assigneeId) {
+    const where = { projectId };
+    if (organizationId) {
+        where.project = {
+            organizationId,
+        };
+    }
+    if (state) {
+        where.state = state;
+    }
+    if (assigneeId) {
+        where.assigneeId = assigneeId;
+    }
+    const tasks = await prisma.task.findMany({
+        where,
+        include: {
+            project: true,
+            assignee: true,
+            creator: true,
+            epic: true,
+        },
+        orderBy: { createdAt: "desc" },
+    });
+    const formattedTasks = await Promise.all(tasks.map(async (task) => {
+        const acceptanceCriteria = await prisma.acceptanceCriterion.findMany({
+            where: { taskId: task.id },
+            orderBy: { order: "asc" },
+        });
+        return {
+            id: task.id,
+            projectId: task.projectId,
+            projectName: task.project?.name || "Unknown",
+            epicId: task.epicId,
+            epicName: task.epic?.name || null,
+            title: task.title,
+            description: task.description,
+            state: task.state,
+            priority: task.priority,
+            assigneeId: task.assigneeId,
+            assigneeName: task.assignee?.name || null,
+            assigneeEmail: task.assignee?.email || null,
+            createdBy: task.createdBy,
+            createdByName: task.creator?.name || null,
+            assignedAt: task.assignedAt,
+            startedAt: task.startedAt,
+            completedAt: task.completedAt,
+            branchName: task.branchName,
+            pullRequestUrl: task.pullRequestUrl,
+            pullRequestNumber: task.pullRequestNumber,
+            errorType: task.errorType,
+            errorMessage: task.errorMessage,
+            acceptanceCriteria: acceptanceCriteria.map((ac) => ({
+                id: ac.id,
+                description: ac.description,
+                completed: ac.completed,
+                completedAt: ac.completedAt,
+                order: ac.order,
+            })),
+            createdAt: task.createdAt,
+            updatedAt: task.updatedAt,
+        };
+    }));
+    return formattedTasks;
+}
+async function getTaskWithChecks(taskId, userId, organizationId) {
+    const task = await prisma.task.findUnique({
+        where: { id: taskId },
+        include: {
+            project: {
+                include: {
+                    organization: true,
+                    projectTags: {
+                        include: { tag: true },
+                    },
+                },
+            },
+            epic: true,
+            assignee: true,
+            creator: true,
+            acceptanceCriteria: {
+                orderBy: { order: "asc" },
+            },
+            progressUpdates: {
+                orderBy: { createdAt: "desc" },
+                take: 10,
+            },
+            notes: {
+                orderBy: { createdAt: "desc" },
+                take: 10,
+            },
+        },
+    });
+    if (!task) {
+        throw new Error("Task not found");
+    }
+    if (organizationId && task.project?.organizationId !== organizationId) {
+        const userTags = await prisma.userTag.findMany({
+            where: { userId },
+            include: { tag: true },
+        });
+        const projectTagNames = new Set(task.project.projectTags?.map((pt) => pt.tag.name) || []);
+        const userTagNames = new Set(userTags.map((ut) => ut.tag.name));
+        const hasAccess = [...userTagNames].some((tag) => projectTagNames.has(tag));
+        if (!hasAccess) {
+            throw new Error("Access denied: Your tags do not grant access to this project");
+        }
+    }
+    const formattedTask = {
+        id: task.id,
+        projectId: task.projectId,
+        projectName: task.project?.name || "Unknown",
+        epicId: task.epicId,
+        epicName: task.epic?.name || null,
+        title: task.title,
+        description: task.description,
+        state: task.state,
+        priority: task.priority,
+        assigneeId: task.assigneeId,
+        assigneeName: task.assignee?.name || null,
+        assigneeEmail: task.assignee?.email || null,
+        createdBy: task.createdBy,
+        createdByName: task.creator?.name || null,
+        assignedAt: task.assignedAt,
+        startedAt: task.startedAt,
+        completedAt: task.completedAt,
+        branchName: task.branchName,
+        pullRequestUrl: task.pullRequestUrl,
+        pullRequestNumber: task.pullRequestNumber,
+        errorType: task.errorType,
+        errorMessage: task.errorMessage,
+        acceptanceCriteria: task.acceptanceCriteria.map((ac) => ({
+            id: ac.id,
+            description: ac.description,
+            completed: ac.completed,
+            completedAt: ac.completedAt,
+            order: ac.order,
+        })),
+        progressUpdates: task.progressUpdates.map((pu) => ({
+            id: pu.id,
+            message: pu.message,
+            checkpoints: pu.checkpoints,
+            userId: pu.userId,
+            createdAt: pu.createdAt,
+        })),
+        notes: task.notes.map((note) => ({
+            id: note.id,
+            content: note.content,
+            userId: note.userId,
+            createdAt: note.createdAt,
+        })),
+        createdAt: task.createdAt,
+        updatedAt: task.updatedAt,
+    };
+    return formattedTask;
+}
+async function assignTask(projectId, taskId, userId, organizationId, expectedState = TaskState.READY) {
+    await ensureAccessControl(projectId, userId, organizationId);
+    const task = await prisma.task.findUnique({
+        where: { id: taskId },
+        include: { project: true },
+    });
+    if (!task) {
+        throw new Error("Task not found");
+    }
+    if (task.state !== expectedState) {
+        return {
+            success: false,
+            taskId,
+            currentState: task.state,
+            message: `Task is already in state: ${task.state}`,
+        };
+    }
+    const repoInfo = GitHubProvider.parseRepositoryUrl(task.project?.repositoryUrl || "");
+    if (!repoInfo) {
+        throw new Error("Invalid repository URL");
+    }
+    const github = getGitHubClient(task.project?.organizationId || "");
+    const branchSuffix = slugify(task.title);
+    const branchName = `feature/${taskId}-${branchSuffix}`;
+    const createResult = await github.createBranch({
+        owner: repoInfo.owner,
+        repo: repoInfo.repo,
+        sourceBranch: task.project?.baseBranch || "develop",
+        newBranch: branchName,
+    });
+    if (!createResult.success) {
+        throw new Error(`Failed to create branch: ${createResult.error}`);
+    }
+    const updatedTask = await prisma.task.update({
+        where: { id: taskId },
+        data: {
+            state: TaskState.IN_PROGRESS,
+            assigneeId: userId,
+            assignedAt: new Date(),
+            branchName,
+            startedAt: new Date(),
+        },
+    });
+    return {
+        success: true,
+        taskId: updatedTask.id,
+        branchName,
+    };
+}
+async function updateProgress(taskId, userId, statusMessage, completedCheckpointIds, _currentCheckpointIndex) {
+    const task = await prisma.task.findUnique({
+        where: { id: taskId },
+    });
+    if (!task) {
+        throw new Error("Task not found");
+    }
+    if (task.assigneeId !== userId) {
+        throw new Error("You are not assigned to this task");
+    }
+    if (completedCheckpointIds && completedCheckpointIds.length > 0) {
+        await prisma.acceptanceCriterion.updateMany({
+            where: {
+                id: { in: completedCheckpointIds },
+            },
+            data: {
+                completed: true,
+                completedAt: new Date(),
+            },
+        });
+    }
+    if (statusMessage) {
+        await prisma.progressUpdate.create({
+            data: {
+                taskId,
+                userId,
+                message: statusMessage,
+                checkpoints: [],
+            },
+        });
+    }
+    const updatedTask = await prisma.task.update({
+        where: { id: taskId },
+        data: {
+            updatedAt: new Date(),
+        },
+    });
+    return {
+        success: true,
+        taskId: updatedTask.id,
+    };
+}
+async function completeTask(projectId, taskId, userId, organizationId, pullRequestTitle, pullRequestBody) {
+    await ensureAccessControl(projectId, userId, organizationId);
+    const task = await prisma.task.findUnique({
+        where: { id: taskId },
+        include: { project: true },
+    });
+    if (!task) {
+        throw new Error("Task not found");
+    }
+    if (task.assigneeId !== userId) {
+        throw new Error("You are not assigned to this task");
+    }
+    if (task.state !== TaskState.IN_PROGRESS) {
+        throw new Error("Task must be in progress to be completed");
+    }
+    if (!task.branchName) {
+        throw new Error("Task has no associated branch");
+    }
+    const repoInfo = GitHubProvider.parseRepositoryUrl(task.project?.repositoryUrl || "");
+    if (!repoInfo) {
+        throw new Error("Invalid repository URL");
+    }
+    const github = getGitHubClient(task.project?.organizationId || "");
+    const acceptanceCriteria = await prisma.acceptanceCriterion.findMany({
+        where: { taskId },
+        orderBy: { order: "asc" },
+    });
+    const acceptanceChecklist = acceptanceCriteria
+        .map((ac) => `- [${ac.completed ? "x" : " "}] ${ac.description}`)
+        .join("\n");
+    const prTitle = pullRequestTitle || `[${taskId}] ${task.title}`;
+    const prBody = pullRequestBody ||
+        `${task.description}\n\n### Acceptance Criteria\n\n${acceptanceChecklist}`;
+    const createResult = await github.createPR({
+        owner: repoInfo.owner,
+        repo: repoInfo.repo,
+        title: prTitle,
+        body: prBody,
+        head: task.branchName,
+        base: task.project?.baseBranch || "develop",
+    });
+    if (!createResult.success) {
+        throw new Error(`Failed to create PR: ${createResult.error}`);
+    }
+    const updatedTask = await prisma.task.update({
+        where: { id: taskId },
+        data: {
+            state: TaskState.REVIEW,
+            completedAt: new Date(),
+            pullRequestUrl: createResult.prUrl,
+            pullRequestNumber: createResult.prNumber,
+        },
+    });
+    return {
+        success: true,
+        taskId: updatedTask.id,
+        prUrl: createResult.prUrl,
+        prNumber: createResult.prNumber,
+    };
+}
+async function checkActiveTask() {
+    const fs = await import("fs");
+    const path = await import("path");
+    const activeTaskPath = path.join(process.cwd(), ".mtaap", "active-task.json");
+    if (!(await fs.promises.access(activeTaskPath).catch(() => false))) {
+        return {
+            hasActiveTask: false,
+            task: null,
+        };
+    }
+    const content = await fs.promises.readFile(activeTaskPath, "utf-8");
+    const activeTask = JSON.parse(content);
+    return {
+        hasActiveTask: true,
+        task: activeTask,
+    };
+}
+async function reportTaskError(taskId, userId, errorType, errorMessage, _context) {
+    const task = await prisma.task.findUnique({
+        where: { id: taskId },
+    });
+    if (!task) {
+        throw new Error("Task not found");
+    }
+    if (task.assigneeId !== userId) {
+        throw new Error("You are not assigned to this task");
+    }
+    const updatedTask = await prisma.task.update({
+        where: { id: taskId },
+        data: {
+            errorType,
+            errorMessage,
+        },
+    });
+    return {
+        success: true,
+        taskId: updatedTask.id,
+    };
+}
+async function getProjectContext(projectId) {
+    const project = await prisma.project.findUnique({
+        where: { id: projectId },
+        include: {
+            organization: {
+                include: { settings: true },
+            },
+        },
+    });
+    if (!project) {
+        throw new Error("Project not found");
+    }
+    const repoInfo = GitHubProvider.parseRepositoryUrl(project.repositoryUrl);
+    let readme = "";
+    let stack = [];
+    if (repoInfo) {
+        const github = getGitHubClient(project.organizationId || "");
+        const readmeResult = await github.getRepositoryReadme(repoInfo.owner, repoInfo.repo);
+        readme = readmeResult || "No README found";
+        const packageJsonResult = await github.getRepositoryPackageJson(repoInfo.owner, repoInfo.repo);
+        if (packageJsonResult) {
+            const packageJson = JSON.parse(packageJsonResult);
+            const deps = {
+                ...packageJson.dependencies,
+                ...packageJson.devDependencies,
+            };
+            stack = Object.keys(deps).slice(0, 20);
+        }
+    }
+    const recentCompletedTasks = await prisma.task.findMany({
+        where: {
+            project: {
+                id: projectId,
+            },
+            state: TaskState.DONE,
+        },
+        orderBy: { completedAt: "desc" },
+        take: 10,
+        include: {
+            creator: {
+                select: { id: true, name: true },
+            },
+        },
+    });
+    const conventions = {
+        branchPrefix: "feature/",
+        commitFormat: project.organization?.settings?.enforceConventionalCommits
+            ? "conventional"
+            : "none",
+        testCommand: "npm test",
+        baseBranch: project.baseBranch || "develop",
+        notes: project.organization?.settings?.maxPersonalProjectsPerUser?.toString() ||
+            "",
+    };
+    return {
+        readme: readme.substring(0, 2000),
+        stack,
+        recentCompleted: recentCompletedTasks.map((task) => ({
+            id: task.id,
+            title: task.title,
+            completedAt: task.completedAt,
+        })),
+        conventions,
+    };
+}
+async function addTaskNote(taskId, userId, content) {
+    const task = await prisma.task.findUnique({
+        where: { id: taskId },
+    });
+    if (!task) {
+        throw new Error("Task not found");
+    }
+    if (task.assigneeId !== userId) {
+        throw new Error("You are not assigned to this task");
+    }
+    const note = await prisma.taskNote.create({
+        data: {
+            taskId,
+            userId,
+            content,
+        },
+    });
+    return {
+        success: true,
+        noteId: note.id,
+    };
+}
+async function abandonTask(taskId, projectId, userId, deleteBranch) {
+    const task = await prisma.task.findUnique({
+        where: { id: taskId },
+        include: { project: true },
+    });
+    if (!task) {
+        throw new Error("Task not found");
+    }
+    // Validate task belongs to specified project
+    if (task.projectId !== projectId) {
+        throw new Error("Task does not belong to the specified project");
+    }
+    if (task.assigneeId !== userId) {
+        throw new Error("You can only abandon tasks you are assigned to");
+    }
+    // Check if repository URL exists before parsing
+    const repositoryUrl = task.project?.repositoryUrl;
+    const repoInfo = repositoryUrl
+        ? GitHubProvider.parseRepositoryUrl(repositoryUrl)
+        : undefined;
+    if (deleteBranch && repoInfo && task.branchName) {
+        const github = getGitHubClient(task.project?.organizationId || "");
+        try {
+            await github.deleteBranch(repoInfo.owner, repoInfo.repo, task.branchName);
+        }
+        catch (error) {
+            console.error("Failed to delete GitHub branch when abandoning task", {
+                taskId,
+                projectId: task.projectId,
+                organizationId: task.project?.organizationId,
+                repositoryOwner: repoInfo.owner,
+                repositoryName: repoInfo.repo,
+                branchName: task.branchName,
+                error,
+            });
+            throw new Error("Failed to delete branch");
+        }
+    }
+    // Use TaskState enum constant instead of string literal
+    const newState = task.state === TaskState.IN_PROGRESS ? TaskState.READY : task.state;
+    const updatedTask = await prisma.task.update({
+        where: { id: taskId },
+        data: {
+            state: newState,
+            assigneeId: null,
+            assignedAt: null,
+            startedAt: null,
+            updatedAt: new Date(),
+        },
+    });
+    return {
+        success: true,
+        taskId: updatedTask.id,
+        state: updatedTask.state,
+        branchDeleted: deleteBranch ? !!repoInfo && !!task.branchName : false,
+    };
+}
+async function createPersonalProject(userId, name, description, repositoryUrl) {
+    const user = await prisma.user.findUnique({
+        where: { id: userId },
+        include: { organizations: true },
+    });
+    if (!user) {
+        throw new Error("User not found");
+    }
+    const repoInfo = GitHubProvider.parseRepositoryUrl(repositoryUrl);
+    if (!repoInfo) {
+        throw new Error("Invalid repository URL");
+    }
+    const github = getGitHubClient(user.organizations[0]?.organizationId || "");
+    const branchInfo = await github.getBranchInfo({
+        owner: repoInfo.owner,
+        repo: repoInfo.repo,
+        branch: "main",
+    });
+    if (!branchInfo) {
+        throw new Error("Could not get repository branch info");
+    }
+    const project = await prisma.project.create({
+        data: {
+            name,
+            description,
+            type: ProjectType.PERSONAL,
+            origin: ProjectOrigin.CREATED,
+            ownerId: userId,
+            organizationId: null,
+            repositoryUrl,
+            baseBranch: "main",
+        },
+    });
+    return {
+        success: true,
+        projectId: project.id,
+    };
+}

package/dist/permissions.d.ts

@@ -0,0 +1,7 @@
+import { ApiKeyPermission } from "@mtaap/core";
+export interface ApiKeyPermissionContext {
+    id?: string;
+    permissions: "READ" | "WRITE" | "ADMIN";
+}
+export declare function assertApiKeyPermission(apiKey: ApiKeyPermissionContext, required: ApiKeyPermission, toolName: string): void;
+//# sourceMappingURL=permissions.d.ts.map

package/dist/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAa/C,MAAM,WAAW,uBAAuB;IACtC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;CACzC;AAED,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,uBAAuB,EAC/B,QAAQ,EAAE,gBAAgB,EAC1B,QAAQ,EAAE,MAAM,GACf,IAAI,CAoBN"}

package/dist/permissions.js

@@ -0,0 +1,25 @@
+/**
+ * Permission levels ranked by access level.
+ * Using string values for compatibility between Prisma's enum and @mtaap/core enum.
+ */
+const PERMISSION_RANK = {
+    READ: 1,
+    WRITE: 2,
+    ADMIN: 3,
+};
+export function assertApiKeyPermission(apiKey, required, toolName) {
+    const actualRank = PERMISSION_RANK[apiKey.permissions] ?? 0;
+    const requiredRank = PERMISSION_RANK[required] ?? 0;
+    if (actualRank >= requiredRank) {
+        return;
+    }
+    console.warn("API key permission violation", {
+        keyId: apiKey.id,
+        requiredPermission: required,
+        actualPermission: apiKey.permissions,
+        tool: toolName,
+    });
+    const error = new Error(`API key lacks required permissions (required: ${required})`);
+    error.status = 403;
+    throw error;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@mtaap/mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "mtaap-mcp": "./dist/cli.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/cli.js",
+    "lint": "eslint src --ext .ts",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^4.3.5",
+    "@mtaap/core": "workspace:*",
+    "@mtaap/db": "workspace:*",
+    "@mtaap/git": "workspace:*",
+    "@mtaap/auth": "workspace:*"
+  },
+  "devDependencies": {
+    "@mtaap/config-typescript": "workspace:*",
+    "typescript": "^5.4.0",
+    "eslint": "^9.39.2",
+    "@types/node": "^25.0.9",
+    "vitest": "^4.0.17",
+    "@vitest/ui": "^4.0.17"
+  }
+}