The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
Add standalone Paperclip MCP server package
dotta8cdba3ce1869
diff --git a/packages/mcp-server/README.md b/packages/mcp-server/README.mdnew file mode 100644index 0000000000..602521e286--- /dev/null+++ b/packages/mcp-server/README.md@@ -0,0 +1,76 @@+# Paperclip MCP Server++Model Context Protocol server for Paperclip.++This package is a thin MCP wrapper over the existing Paperclip REST API. It does+not talk to the database directly and it does not reimplement business logic.++## Authentication++The server reads its configuration from environment variables:++- `PAPERCLIP_API_URL` - Paperclip base URL, for example `http://localhost:3100`+- `PAPERCLIP_API_KEY` - bearer token used for `/api` requests+- `PAPERCLIP_COMPANY_ID` - optional default company for company-scoped tools+- `PAPERCLIP_AGENT_ID` - optional default agent for checkout helpers+- `PAPERCLIP_RUN_ID` - optional run id forwarded on mutating requests++## Usage++```sh+npx -y @paperclipai/mcp-server+```++Or locally in this repo:++```sh+pnpm --filter @paperclipai/mcp-server build+node packages/mcp-server/dist/stdio.js+```++## Tool Surface++Read tools:++- `paperclipMe`+- `paperclipInboxLite`+- `paperclipListAgents`+- `paperclipGetAgent`+- `paperclipListIssues`+- `paperclipGetIssue`+- `paperclipGetHeartbeatContext`+- `paperclipListComments`+- `paperclipGetComment`+- `paperclipListIssueApprovals`+- `paperclipListDocuments`+- `paperclipGetDocument`+- `paperclipListDocumentRevisions`+- `paperclipListProjects`+- `paperclipGetProject`+- `paperclipListGoals`+- `paperclipGetGoal`+- `paperclipListApprovals`+- `paperclipGetApproval`+- `paperclipGetApprovalIssues`+- `paperclipListApprovalComments`++Write tools:++- `paperclipCreateIssue`+- `paperclipUpdateIssue`+- `paperclipCheckoutIssue`+- `paperclipReleaseIssue`+- `paperclipAddComment`+- `paperclipUpsertIssueDocument`+- `paperclipRestoreIssueDocumentRevision`+- `paperclipLinkIssueApproval`+- `paperclipUnlinkIssueApproval`+- `paperclipApprovalDecision`+- `paperclipAddApprovalComment`++Escape hatch:++- `paperclipApiRequest`++`paperclipApiRequest` is limited to paths under `/api` and JSON bodies. It is+meant for endpoints that do not yet have a dedicated MCP tool.diff --git a/packages/mcp-server/package.json b/packages/mcp-server/package.jsonnew file mode 100644index 0000000000..6edba34dc0--- /dev/null+++ b/packages/mcp-server/package.json@@ -0,0 +1,55 @@+{+ "name": "@paperclipai/mcp-server",+ "version": "0.1.0",+ "license": "MIT",+ "homepage": "https://github.com/paperclipai/paperclip",+ "bugs": {+ "url": "https://github.com/paperclipai/paperclip/issues"+ },+ "repository": {+ "type": "git",+ "url": "https://github.com/paperclipai/paperclip",+ "directory": "packages/mcp-server"+ },+ "type": "module",+ "bin": {+ "paperclip-mcp-server": "./dist/stdio.js"+ },+ "exports": {+ ".": "./src/index.ts"+ },+ "publishConfig": {+ "access": "public",+ "bin": {+ "paperclip-mcp-server": "./dist/stdio.js"+ },+ "exports": {+ ".": {+ "types": "./dist/index.d.ts",+ "import": "./dist/index.js"+ }+ },+ "main": "./dist/index.js",+ "types": "./dist/index.d.ts"+ },+ "files": [+ "dist",+ "README.md"+ ],+ "scripts": {+ "build": "tsc",+ "clean": "rm -rf dist",+ "typecheck": "tsc --noEmit",+ "test": "vitest run"+ },+ "dependencies": {+ "@modelcontextprotocol/sdk": "^1.29.0",+ "@paperclipai/shared": "workspace:*",+ "zod": "^3.24.2"+ },+ "devDependencies": {+ "@types/node": "^24.6.0",+ "typescript": "^5.7.3",+ "vitest": "^3.0.5"+ }+}diff --git a/packages/mcp-server/src/client.ts b/packages/mcp-server/src/client.tsnew file mode 100644index 0000000000..a2fd8e356b--- /dev/null+++ b/packages/mcp-server/src/client.ts@@ -0,0 +1,114 @@+import type { PaperclipMcpConfig } from "./config.js";++export class PaperclipApiError extends Error {+ readonly status: number;+ readonly method: string;+ readonly path: string;+ readonly body: unknown;++ constructor(input: {+ status: number;+ method: string;+ path: string;+ body: unknown;+ message: string;+ }) {+ super(input.message);+ this.name = "PaperclipApiError";+ this.status = input.status;+ this.method = input.method;+ this.path = input.path;+ this.body = input.body;+ }+}++export interface JsonRequestOptions {+ body?: unknown;+ includeRunId?: boolean;+}++function isWriteMethod(method: string): boolean {+ return !["GET", "HEAD"].includes(method.toUpperCase());+}++function buildErrorMessage(method: string, path: string, status: number, body: unknown): string {+ if (body && typeof body === "object" && "error" in body && typeof body.error === "string") {+ return `${method} ${path} failed with ${status}: ${body.error}`;+ }+ return `${method} ${path} failed with ${status}`;+}++async function parseResponseBody(response: Response): Promise<unknown> {+ const text = await response.text();+ if (!text) return null;+ try {+ return JSON.parse(text) as unknown;+ } catch {+ return text;+ }+}++export class PaperclipApiClient {+ constructor(private readonly config: PaperclipMcpConfig) {}++ get defaults() {+ return {+ companyId: this.config.companyId,+ agentId: this.config.agentId,+ runId: this.config.runId,+ };+ }++ resolveCompanyId(companyId?: string | null): string {+ const resolved = companyId?.trim() || this.config.companyId;+ if (!resolved) {+ throw new Error("companyId is required because PAPERCLIP_COMPANY_ID is not set");+ }+ return resolved;+ }++ resolveAgentId(agentId?: string | null): string {+ const resolved = agentId?.trim() || this.config.agentId;+ if (!resolved) {+ throw new Error("agentId is required because PAPERCLIP_AGENT_ID is not set");+ }+ return resolved;+ }++ async requestJson<T>(method: string, path: string, options: JsonRequestOptions = {}): Promise<T> {+ if (!path.startsWith("/")) {+ throw new Error(`API path must start with "/": ${path}`);+ }++ const url = new URL(path.slice(1), `${this.config.apiUrl}/`);+ const headers: Record<string, string> = {+ Authorization: `Bearer ${this.config.apiKey}`,+ Accept: "application/json",+ };+ if (options.body !== undefined) {+ headers["Content-Type"] = "application/json";+ }+ if ((options.includeRunId ?? isWriteMethod(method)) && this.config.runId) {+ headers["X-Paperclip-Run-Id"] = this.config.runId;+ }++ const response = await fetch(url, {+ method,+ headers,+ body: options.body === undefined ? undefined : JSON.stringify(options.body),+ });+ const parsedBody = await parseResponseBody(response);++ if (!response.ok) {+ throw new PaperclipApiError({+ status: response.status,+ method: method.toUpperCase(),+ path,+ body: parsedBody,+ message: buildErrorMessage(method.toUpperCase(), path, response.status, parsedBody),+ });+ }++ return parsedBody as T;+ }+}diff --git a/packages/mcp-server/src/config.ts b/packages/mcp-server/src/config.tsnew file mode 100644index 0000000000..c1de29eb4f--- /dev/null+++ b/packages/mcp-server/src/config.ts@@ -0,0 +1,39 @@+export interface PaperclipMcpConfig {+ apiUrl: string;+ apiKey: string;+ companyId: string | null;+ agentId: string | null;+ runId: string | null;+}++function nonEmpty(value: string | undefined): string | null {+ return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;+}++function stripTrailingSlash(value: string): string {+ return value.replace(/\/+$/, "");+}++export function normalizeApiUrl(apiUrl: string): string {+ const trimmed = stripTrailingSlash(apiUrl.trim());+ return trimmed.endsWith("/api") ? trimmed : `${trimmed}/api`;+}++export function readConfigFromEnv(env: NodeJS.ProcessEnv = process.env): PaperclipMcpConfig {+ const apiUrl = nonEmpty(env.PAPERCLIP_API_URL);+ if (!apiUrl) {+ throw new Error("Missing PAPERCLIP_API_URL");+ }+ const apiKey = nonEmpty(env.PAPERCLIP_API_KEY);+ if (!apiKey) {+ throw new Error("Missing PAPERCLIP_API_KEY");+ }++ return {+ apiUrl: normalizeApiUrl(apiUrl),+ apiKey,+ companyId: nonEmpty(env.PAPERCLIP_COMPANY_ID),+ agentId: nonEmpty(env.PAPERCLIP_AGENT_ID),+ runId: nonEmpty(env.PAPERCLIP_RUN_ID),+ };+}diff --git a/packages/mcp-server/src/format.ts b/packages/mcp-server/src/format.tsnew file mode 100644index 0000000000..b2e6a4cd25--- /dev/null+++ b/packages/mcp-server/src/format.ts@@ -0,0 +1,31 @@+import { PaperclipApiError } from "./client.js";++type McpTextResponse = {+ content: Array<{ type: "text"; text: string }>;+};++export function formatTextResponse(value: unknown): McpTextResponse {+ return {+ content: [+ {+ type: "text",+ text: typeof value === "string" ? value : JSON.stringify(value, null, 2),+ },+ ],+ };+}++export function formatErrorResponse(error: unknown): McpTextResponse {+ if (error instanceof PaperclipApiError) {+ return formatTextResponse({+ error: error.message,+ status: error.status,+ method: error.method,+ path: error.path,+ body: error.body,+ });+ }+ return formatTextResponse({+ error: error instanceof Error ? error.message : String(error),+ });+}diff --git a/packages/mcp-server/src/index.ts b/packages/mcp-server/src/index.tsnew file mode 100644index 0000000000..dc9fdc5cd7--- /dev/null+++ b/packages/mcp-server/src/index.ts@@ -0,0 +1,30 @@+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";+import { PaperclipApiClient } from "./client.js";+import { readConfigFromEnv, type PaperclipMcpConfig } from "./config.js";+import { createToolDefinitions } from "./tools.js";++export function createPaperclipMcpServer(config: PaperclipMcpConfig = readConfigFromEnv()) {+ const server = new McpServer({+ name: "paperclip",+ version: "0.1.0",+ });++ const client = new PaperclipApiClient(config);+ const tools = createToolDefinitions(client);+ for (const tool of tools) {+ server.tool(tool.name, tool.description, tool.schema.shape, tool.execute);+ }++ return {+ server,+ tools,+ client,+ };+}++export async function runServer(config: PaperclipMcpConfig = readConfigFromEnv()) {+ const { server } = createPaperclipMcpServer(config);+ const transport = new StdioServerTransport();+ await server.connect(transport);+}diff --git a/packages/mcp-server/src/stdio.ts b/packages/mcp-server/src/stdio.tsnew file mode 100644index 0000000000..145b236285--- /dev/null+++ b/packages/mcp-server/src/stdio.ts@@ -0,0 +1,7 @@+#!/usr/bin/env node+import { runServer } from "./index.js";++void runServer().catch((error) => {+ console.error("Failed to start Paperclip MCP server:", error);+ process.exit(1);+});diff --git a/packages/mcp-server/src/tools.test.ts b/packages/mcp-server/src/tools.test.tsnew file mode 100644index 0000000000..f1d222857b--- /dev/null+++ b/packages/mcp-server/src/tools.test.ts@@ -0,0 +1,121 @@+import { beforeEach, describe, expect, it, vi } from "vitest";+import { PaperclipApiClient } from "./client.js";+import { createToolDefinitions } from "./tools.js";++function makeClient() {+ return new PaperclipApiClient({+ apiUrl: "http://localhost:3100/api",+ apiKey: "token-123",+ companyId: "11111111-1111-1111-1111-111111111111",+ agentId: "22222222-2222-2222-2222-222222222222",+ runId: "33333333-3333-3333-3333-333333333333",+ });+}++function getTool(name: string) {+ const tool = createToolDefinitions(makeClient()).find((candidate) => candidate.name === name);+ if (!tool) throw new Error(`Missing tool ${name}`);+ return tool;+}++function mockJsonResponse(body: unknown, status = 200) {+ return new Response(JSON.stringify(body), {+ status,+ headers: { "Content-Type": "application/json" },+ });+}++describe("paperclip MCP tools", () => {+ beforeEach(() => {+ vi.restoreAllMocks();+ });++ it("adds auth headers and run id to mutating requests", async () => {+ const fetchMock = vi.fn().mockResolvedValue(+ mockJsonResponse({ ok: true }),+ );+ vi.stubGlobal("fetch", fetchMock);++ const tool = getTool("paperclipUpdateIssue");+ await tool.execute({+ issueId: "PAP-1135",+ status: "done",+ });++ expect(fetchMock).toHaveBeenCalledTimes(1);+ const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];+ expect(String(url)).toBe("http://localhost:3100/api/issues/PAP-1135");+ expect(init.method).toBe("PATCH");+ expect((init.headers as Record<string, string>)["Authorization"]).toBe("Bearer token-123");+ expect((init.headers as Record<string, string>)["X-Paperclip-Run-Id"]).toBe(+ "33333333-3333-3333-3333-333333333333",+ );+ });++ it("uses default company id for company-scoped list tools", async () => {+ const fetchMock = vi.fn().mockResolvedValue(+ mockJsonResponse([{ id: "issue-1" }]),+ );+ vi.stubGlobal("fetch", fetchMock);++ const tool = getTool("paperclipListIssues");+ const response = await tool.execute({});++ expect(fetchMock).toHaveBeenCalledTimes(1);+ const [url] = fetchMock.mock.calls[0] as [string];+ expect(String(url)).toBe(+ "http://localhost:3100/api/companies/11111111-1111-1111-1111-111111111111/issues",+ );+ expect(response.content[0]?.text).toContain("issue-1");+ });++ it("uses default agent id for checkout requests", async () => {+ const fetchMock = vi.fn().mockResolvedValue(+ mockJsonResponse({ id: "PAP-1135", status: "in_progress" }),+ );+ vi.stubGlobal("fetch", fetchMock);++ const tool = getTool("paperclipCheckoutIssue");+ await tool.execute({+ issueId: "PAP-1135",+ });++ const [, init] = fetchMock.mock.calls[0] as [string, RequestInit];+ expect(JSON.parse(String(init.body))).toEqual({+ agentId: "22222222-2222-2222-2222-222222222222",+ expectedStatuses: ["todo", "backlog", "blocked"],+ });+ });++ it("defaults issue document format to markdown", async () => {+ const fetchMock = vi.fn().mockResolvedValue(+ mockJsonResponse({ key: "plan", latestRevisionNumber: 2 }),+ );+ vi.stubGlobal("fetch", fetchMock);++ const tool = getTool("paperclipUpsertIssueDocument");+ await tool.execute({+ issueId: "PAP-1135",+ key: "plan",+ body: "# Updated",+ });++ const [, init] = fetchMock.mock.calls[0] as [string, RequestInit];+ expect(JSON.parse(String(init.body))).toEqual({+ format: "markdown",+ body: "# Updated",+ });+ });++ it("rejects invalid generic request paths", async () => {+ vi.stubGlobal("fetch", vi.fn());++ const tool = getTool("paperclipApiRequest");+ const response = await tool.execute({+ method: "GET",+ path: "issues",+ });++ expect(response.content[0]?.text).toContain("path must start with /");+ });+});diff --git a/packages/mcp-server/src/tools.ts b/packages/mcp-server/src/tools.tsnew file mode 100644index 0000000000..cfed2f6638--- /dev/null+++ b/packages/mcp-server/src/tools.ts@@ -0,0 +1,413 @@+import { z } from "zod";+import {+ addIssueCommentSchema,+ checkoutIssueSchema,+ createIssueSchema,+ updateIssueSchema,+ upsertIssueDocumentSchema,+ linkIssueApprovalSchema,+} from "@paperclipai/shared";+import { PaperclipApiClient } from "./client.js";+import { formatErrorResponse, formatTextResponse } from "./format.js";++export interface ToolDefinition {+ name: string;+ description: string;+ schema: z.AnyZodObject;+ execute: (input: Record<string, unknown>) => Promise<{+ content: Array<{ type: "text"; text: string }>;+ }>;+}++function makeTool<TSchema extends z.ZodRawShape>(+ name: string,+ description: string,+ schema: z.ZodObject<TSchema>,+ execute: (input: z.infer<typeof schema>) => Promise<unknown>,+): ToolDefinition {+ return {+ name,+ description,+ schema,+ execute: async (input) => {+ try {+ const parsed = schema.parse(input);+ return formatTextResponse(await execute(parsed));+ } catch (error) {+ return formatErrorResponse(error);+ }+ },+ };+}++function parseOptionalJson(raw: string | undefined | null): unknown {+ if (!raw || raw.trim().length === 0) return undefined;+ return JSON.parse(raw);+}++const companyIdOptional = z.string().uuid().optional().nullable();+const agentIdOptional = z.string().uuid().optional().nullable();+const issueIdSchema = z.string().min(1);+const projectIdSchema = z.string().min(1);+const goalIdSchema = z.string().uuid();+const approvalIdSchema = z.string().uuid();+const documentKeySchema = z.string().trim().min(1).max(64);++const listIssuesSchema = z.object({+ companyId: companyIdOptional,+ status: z.string().optional(),+ projectId: z.string().uuid().optional(),+ assigneeAgentId: z.string().uuid().optional(),+ participantAgentId: z.string().uuid().optional(),+ assigneeUserId: z.string().optional(),+ touchedByUserId: z.string().optional(),+ inboxArchivedByUserId: z.string().optional(),+ unreadForUserId: z.string().optional(),+ labelId: z.string().uuid().optional(),+ executionWorkspaceId: z.string().uuid().optional(),+ originKind: z.string().optional(),+ originId: z.string().optional(),+ includeRoutineExecutions: z.boolean().optional(),+ q: z.string().optional(),+});++const listCommentsSchema = z.object({+ issueId: issueIdSchema,+ after: z.string().uuid().optional(),+ order: z.enum(["asc", "desc"]).optional(),+ limit: z.number().int().positive().max(500).optional(),+});++const upsertDocumentToolSchema = z.object({+ issueId: issueIdSchema,+ key: documentKeySchema,+ title: z.string().trim().max(200).nullable().optional(),+ format: z.enum(["markdown"]).default("markdown"),+ body: z.string().max(524288),+ changeSummary: z.string().trim().max(500).nullable().optional(),+ baseRevisionId: z.string().uuid().nullable().optional(),+});++const createIssueToolSchema = z.object({+ companyId: companyIdOptional,+}).merge(createIssueSchema);++const updateIssueToolSchema = z.object({+ issueId: issueIdSchema,+}).merge(updateIssueSchema);++const checkoutIssueToolSchema = z.object({+ issueId: issueIdSchema,+ agentId: agentIdOptional,+ expectedStatuses: checkoutIssueSchema.shape.expectedStatuses.optional(),+});++const addCommentToolSchema = z.object({+ issueId: issueIdSchema,+}).merge(addIssueCommentSchema);++const approvalDecisionSchema = z.object({+ approvalId: approvalIdSchema,+ action: z.enum(["approve", "reject", "requestRevision", "resubmit"]),+ decisionNote: z.string().optional(),+ payloadJson: z.string().optional(),+});++const apiRequestSchema = z.object({+ method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),+ path: z.string().min(1),+ jsonBody: z.string().optional(),+});++export function createToolDefinitions(client: PaperclipApiClient): ToolDefinition[] {+ return [+ makeTool(+ "paperclipMe",+ "Get the current authenticated Paperclip actor details",+ z.object({}),+ async () => client.requestJson("GET", "/agents/me"),+ ),+ makeTool(+ "paperclipInboxLite",+ "Get the current authenticated agent inbox-lite assignment list",+ z.object({}),+ async () => client.requestJson("GET", "/agents/me/inbox-lite"),+ ),+ makeTool(+ "paperclipListAgents",+ "List agents in a company",+ z.object({ companyId: companyIdOptional }),+ async ({ companyId }) => client.requestJson("GET", `/companies/${client.resolveCompanyId(companyId)}/agents`),+ ),+ makeTool(+ "paperclipGetAgent",+ "Get a single agent by id",+ z.object({ agentId: z.string().min(1), companyId: companyIdOptional }),+ async ({ agentId, companyId }) => {+ const qs = companyId ? `?companyId=${encodeURIComponent(companyId)}` : "";+ return client.requestJson("GET", `/agents/${encodeURIComponent(agentId)}${qs}`);+ },+ ),+ makeTool(+ "paperclipListIssues",+ "List issues for a company with optional filters",+ listIssuesSchema,+ async (input) => {+ const companyId = client.resolveCompanyId(input.companyId);+ const params = new URLSearchParams();+ for (const [key, value] of Object.entries(input)) {+ if (key === "companyId" || value === undefined || value === null) continue;+ params.set(key, String(value));+ }+ const qs = params.toString();+ return client.requestJson("GET", `/companies/${companyId}/issues${qs ? `?${qs}` : ""}`);+ },+ ),+ makeTool(+ "paperclipGetIssue",+ "Get a single issue by UUID or identifier",+ z.object({ issueId: issueIdSchema }),+ async ({ issueId }) => client.requestJson("GET", `/issues/${encodeURIComponent(issueId)}`),+ ),+ makeTool(+ "paperclipGetHeartbeatContext",+ "Get compact heartbeat context for an issue",+ z.object({ issueId: issueIdSchema, wakeCommentId: z.string().uuid().optional() }),+ async ({ issueId, wakeCommentId }) => {+ const qs = wakeCommentId ? `?wakeCommentId=${encodeURIComponent(wakeCommentId)}` : "";+ return client.requestJson("GET", `/issues/${encodeURIComponent(issueId)}/heartbeat-context${qs}`);+ },+ ),+ makeTool(+ "paperclipListComments",+ "List issue comments with incremental options",+ listCommentsSchema,+ async ({ issueId, after, order, limit }) => {+ const params = new URLSearchParams();+ if (after) params.set("after", after);+ if (order) params.set("order", order);+ if (limit) params.set("limit", String(limit));+ const qs = params.toString();+ return client.requestJson("GET", `/issues/${encodeURIComponent(issueId)}/comments${qs ? `?${qs}` : ""}`);+ },+ ),+ makeTool(+ "paperclipGetComment",+ "Get a specific issue comment by id",+ z.object({ issueId: issueIdSchema, commentId: z.string().uuid() }),+ async ({ issueId, commentId }) =>+ client.requestJson("GET", `/issues/${encodeURIComponent(issueId)}/comments/${encodeURIComponent(commentId)}`),+ ),+ makeTool(+ "paperclipListIssueApprovals",+ "List approvals linked to an issue",+ z.object({ issueId: issueIdSchema }),+ async ({ issueId }) => client.requestJson("GET", `/issues/${encodeURIComponent(issueId)}/approvals`),+ ),+ makeTool(+ "paperclipListDocuments",+ "List issue documents",+ z.object({ issueId: issueIdSchema }),+ async ({ issueId }) => client.requestJson("GET", `/issues/${encodeURIComponent(issueId)}/documents`),+ ),+ makeTool(+ "paperclipGetDocument",+ "Get one issue document by key",+ z.object({ issueId: issueIdSchema, key: documentKeySchema }),+ async ({ issueId, key }) =>+ client.requestJson("GET", `/issues/${encodeURIComponent(issueId)}/documents/${encodeURIComponent(key)}`),+ ),+ makeTool(+ "paperclipListDocumentRevisions",+ "List revisions for an issue document",+ z.object({ issueId: issueIdSchema, key: documentKeySchema }),+ async ({ issueId, key }) =>+ client.requestJson(+ "GET",+ `/issues/${encodeURIComponent(issueId)}/documents/${encodeURIComponent(key)}/revisions`,+ ),+ ),+ makeTool(+ "paperclipListProjects",+ "List projects in a company",+ z.object({ companyId: companyIdOptional }),+ async ({ companyId }) => client.requestJson("GET", `/companies/${client.resolveCompanyId(companyId)}/projects`),+ ),+ makeTool(+ "paperclipGetProject",+ "Get a project by id or company-scoped short reference",+ z.object({ projectId: projectIdSchema, companyId: companyIdOptional }),+ async ({ projectId, companyId }) => {+ const qs = companyId ? `?companyId=${encodeURIComponent(companyId)}` : "";+ return client.requestJson("GET", `/projects/${encodeURIComponent(projectId)}${qs}`);+ },+ ),+ makeTool(+ "paperclipListGoals",+ "List goals in a company",+ z.object({ companyId: companyIdOptional }),+ async ({ companyId }) => client.requestJson("GET", `/companies/${client.resolveCompanyId(companyId)}/goals`),+ ),+ makeTool(+ "paperclipGetGoal",+ "Get a goal by id",+ z.object({ goalId: goalIdSchema }),+ async ({ goalId }) => client.requestJson("GET", `/goals/${encodeURIComponent(goalId)}`),+ ),+ makeTool(+ "paperclipListApprovals",+ "List approvals in a company",+ z.object({ companyId: companyIdOptional, status: z.string().optional() }),+ async ({ companyId, status }) => {+ const qs = status ? `?status=${encodeURIComponent(status)}` : "";+ return client.requestJson("GET", `/companies/${client.resolveCompanyId(companyId)}/approvals${qs}`);+ },+ ),+ makeTool(+ "paperclipGetApproval",+ "Get an approval by id",+ z.object({ approvalId: approvalIdSchema }),+ async ({ approvalId }) => client.requestJson("GET", `/approvals/${encodeURIComponent(approvalId)}`),+ ),+ makeTool(+ "paperclipGetApprovalIssues",+ "List issues linked to an approval",+ z.object({ approvalId: approvalIdSchema }),+ async ({ approvalId }) => client.requestJson("GET", `/approvals/${encodeURIComponent(approvalId)}/issues`),+ ),+ makeTool(+ "paperclipListApprovalComments",+ "List comments for an approval",+ z.object({ approvalId: approvalIdSchema }),+ async ({ approvalId }) => client.requestJson("GET", `/approvals/${encodeURIComponent(approvalId)}/comments`),+ ),+ makeTool(+ "paperclipCreateIssue",+ "Create a new issue",+ createIssueToolSchema,+ async ({ companyId, ...body }) =>+ client.requestJson("POST", `/companies/${client.resolveCompanyId(companyId)}/issues`, { body }),+ ),+ makeTool(+ "paperclipUpdateIssue",+ "Patch an issue, optionally including a comment",+ updateIssueToolSchema,+ async ({ issueId, ...body }) =>+ client.requestJson("PATCH", `/issues/${encodeURIComponent(issueId)}`, { body }),+ ),+ makeTool(+ "paperclipCheckoutIssue",+ "Checkout an issue for an agent",+ checkoutIssueToolSchema,+ async ({ issueId, agentId, expectedStatuses }) =>+ client.requestJson("POST", `/issues/${encodeURIComponent(issueId)}/checkout`, {+ body: {+ agentId: client.resolveAgentId(agentId),+ expectedStatuses: expectedStatuses ?? ["todo", "backlog", "blocked"],+ },+ }),+ ),+ makeTool(+ "paperclipReleaseIssue",+ "Release an issue checkout",+ z.object({ issueId: issueIdSchema }),+ async ({ issueId }) => client.requestJson("POST", `/issues/${encodeURIComponent(issueId)}/release`, { body: {} }),+ ),+ makeTool(+ "paperclipAddComment",+ "Add a comment to an issue",+ addCommentToolSchema,+ async ({ issueId, ...body }) =>+ client.requestJson("POST", `/issues/${encodeURIComponent(issueId)}/comments`, { body }),+ ),+ makeTool(+ "paperclipUpsertIssueDocument",+ "Create or update an issue document",+ upsertDocumentToolSchema,+ async ({ issueId, key, ...body }) =>+ client.requestJson(+ "PUT",+ `/issues/${encodeURIComponent(issueId)}/documents/${encodeURIComponent(key)}`,+ { body },+ ),+ ),+ makeTool(+ "paperclipRestoreIssueDocumentRevision",+ "Restore a prior revision of an issue document",+ z.object({+ issueId: issueIdSchema,+ key: documentKeySchema,+ revisionId: z.string().uuid(),+ }),+ async ({ issueId, key, revisionId }) =>+ client.requestJson(+ "POST",+ `/issues/${encodeURIComponent(issueId)}/documents/${encodeURIComponent(key)}/revisions/${encodeURIComponent(revisionId)}/restore`,+ { body: {} },+ ),+ ),+ makeTool(+ "paperclipLinkIssueApproval",+ "Link an approval to an issue",+ z.object({ issueId: issueIdSchema }).merge(linkIssueApprovalSchema),+ async ({ issueId, approvalId }) =>+ client.requestJson("POST", `/issues/${encodeURIComponent(issueId)}/approvals`, {+ body: { approvalId },+ }),+ ),+ makeTool(+ "paperclipUnlinkIssueApproval",+ "Unlink an approval from an issue",+ z.object({ issueId: issueIdSchema, approvalId: approvalIdSchema }),+ async ({ issueId, approvalId }) =>+ client.requestJson(+ "DELETE",+ `/issues/${encodeURIComponent(issueId)}/approvals/${encodeURIComponent(approvalId)}`,+ ),+ ),+ makeTool(+ "paperclipApprovalDecision",+ "Approve, reject, request revision, or resubmit an approval",+ approvalDecisionSchema,+ async ({ approvalId, action, decisionNote, payloadJson }) => {+ const path =+ action === "approve"+ ? `/approvals/${encodeURIComponent(approvalId)}/approve`+ : action === "reject"+ ? `/approvals/${encodeURIComponent(approvalId)}/reject`+ : action === "requestRevision"+ ? `/approvals/${encodeURIComponent(approvalId)}/request-revision`+ : `/approvals/${encodeURIComponent(approvalId)}/resubmit`;++ const body =+ action === "resubmit"+ ? { payload: parseOptionalJson(payloadJson) ?? {} }+ : { decisionNote };++ return client.requestJson("POST", path, { body });+ },+ ),+ makeTool(+ "paperclipAddApprovalComment",+ "Add a comment to an approval",+ z.object({ approvalId: approvalIdSchema, body: z.string().min(1) }),+ async ({ approvalId, body }) =>+ client.requestJson("POST", `/approvals/${encodeURIComponent(approvalId)}/comments`, {+ body: { body },+ }),+ ),+ makeTool(+ "paperclipApiRequest",+ "Make a JSON request to an existing Paperclip /api endpoint for unsupported operations",+ apiRequestSchema,+ async ({ method, path, jsonBody }) => {+ if (!path.startsWith("/")) {+ throw new Error("path must start with / and be relative to /api");+ }+ return client.requestJson(method, path, {+ body: parseOptionalJson(jsonBody),+ });+ },+ ),+ ];+}diff --git a/packages/mcp-server/tsconfig.json b/packages/mcp-server/tsconfig.jsonnew file mode 100644index 0000000000..5a24989cd3--- /dev/null+++ b/packages/mcp-server/tsconfig.json@@ -0,0 +1,8 @@+{+ "extends": "../../tsconfig.base.json",+ "compilerOptions": {+ "outDir": "dist",+ "rootDir": "src"+ },+ "include": ["src"]+}diff --git a/packages/mcp-server/vitest.config.ts b/packages/mcp-server/vitest.config.tsnew file mode 100644index 0000000000..f624398e8d--- /dev/null+++ b/packages/mcp-server/vitest.config.ts@@ -0,0 +1,7 @@+import { defineConfig } from "vitest/config";++export default defineConfig({+ test: {+ environment: "node",+ },+});diff --git a/tsconfig.json b/tsconfig.jsonindex 9a5267db6e..e597c33111 100644--- a/tsconfig.json+++ b/tsconfig.json@@ -3,6 +3,7 @@"files": [],"references": [{ "path": "./packages/adapter-utils" },+ { "path": "./packages/mcp-server" },{ "path": "./packages/shared" },{ "path": "./packages/db" },{ "path": "./packages/adapters/claude-local" },