@artyfacts/mcp-server 1.1.5 → 1.3.0

package/dist/chunk-U2KVKQ6X.js

@@ -0,0 +1,692 @@
+// src/server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+var ARTYFACTS_TOOLS = [
+  // Organization tools
+  {
+    name: "get_organization",
+    description: "Get details about the current organization",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: []
+    }
+  },
+  // Project tools
+  {
+    name: "list_projects",
+    description: "List all projects in the organization",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "number", description: "Max results (default 50)" },
+        offset: { type: "number", description: "Pagination offset" }
+      },
+      required: []
+    }
+  },
+  {
+    name: "get_project",
+    description: "Get details about a specific project",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id: { type: "string", description: "Project ID" }
+      },
+      required: ["project_id"]
+    }
+  },
+  // Artifact tools
+  {
+    name: "list_artifacts",
+    description: "List artifacts, optionally filtered by project",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id: { type: "string", description: "Filter by project" },
+        type: { type: "string", description: "Filter by type (goal, spec, research, etc.)" },
+        status: { type: "string", description: "Filter by status" },
+        limit: { type: "number", description: "Max results" }
+      },
+      required: []
+    }
+  },
+  {
+    name: "get_artifact",
+    description: "Get a specific artifact by ID",
+    inputSchema: {
+      type: "object",
+      properties: {
+        artifact_id: { type: "string", description: "Artifact ID" }
+      },
+      required: ["artifact_id"]
+    }
+  },
+  {
+    name: "create_artifact",
+    description: "Create a new artifact (document, goal, spec, etc.)",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: { type: "string", description: "Artifact title" },
+        type: { type: "string", description: "Artifact type: goal, spec, research, report, experiment, decision, doc" },
+        content: { type: "string", description: "Markdown content" },
+        goal_id: { type: "string", description: "The goal UUID this artifact belongs to \u2014 always pass this when working on a task" },
+        parent_id: { type: "string", description: "Parent artifact ID for nested artifacts" },
+        tags: { type: "array", items: { type: "string" }, description: "Tags for categorization" }
+      },
+      required: ["title", "type"]
+    }
+  },
+  {
+    name: "update_artifact",
+    description: "Update an existing artifact",
+    inputSchema: {
+      type: "object",
+      properties: {
+        artifact_id: { type: "string", description: "Artifact ID" },
+        title: { type: "string", description: "New title" },
+        content: { type: "string", description: "New content" },
+        status: { type: "string", description: "New status" }
+      },
+      required: ["artifact_id"]
+    }
+  },
+  // Section tools
+  {
+    name: "list_sections",
+    description: "List sections of an artifact",
+    inputSchema: {
+      type: "object",
+      properties: {
+        artifact_id: { type: "string", description: "Artifact ID" }
+      },
+      required: ["artifact_id"]
+    }
+  },
+  {
+    name: "get_section",
+    description: "Get a specific section",
+    inputSchema: {
+      type: "object",
+      properties: {
+        artifact_id: { type: "string", description: "Artifact ID" },
+        section_id: { type: "string", description: "Section ID" }
+      },
+      required: ["artifact_id", "section_id"]
+    }
+  },
+  {
+    name: "create_section",
+    description: "Create a new section on an artifact",
+    inputSchema: {
+      type: "object",
+      properties: {
+        artifact_id: { type: "string", description: "Artifact ID" },
+        section_id: { type: "string", description: "Section identifier (slug)" },
+        heading: { type: "string", description: "Section heading" },
+        content: { type: "string", description: "Markdown content" },
+        type: { type: "string", description: "Type: content, task, decision, blocker" },
+        position: { type: "number", description: "Order position" }
+      },
+      required: ["artifact_id", "section_id", "heading", "content"]
+    }
+  },
+  {
+    name: "update_section",
+    description: "Update an existing section",
+    inputSchema: {
+      type: "object",
+      properties: {
+        artifact_id: { type: "string", description: "Artifact ID" },
+        section_id: { type: "string", description: "Section ID" },
+        heading: { type: "string", description: "New heading" },
+        content: { type: "string", description: "New content" },
+        task_status: { type: "string", description: "Task status if type=task" }
+      },
+      required: ["artifact_id", "section_id"]
+    }
+  },
+  {
+    name: "delete_section",
+    description: "Delete a section",
+    inputSchema: {
+      type: "object",
+      properties: {
+        artifact_id: { type: "string", description: "Artifact ID" },
+        section_id: { type: "string", description: "Section ID" }
+      },
+      required: ["artifact_id", "section_id"]
+    }
+  },
+  // Task tools
+  {
+    name: "list_tasks",
+    description: "List tasks (sections with type=task)",
+    inputSchema: {
+      type: "object",
+      properties: {
+        artifact_id: { type: "string", description: "Filter by artifact" },
+        status: { type: "string", description: "Filter by status: pending, in_progress, done, blocked" },
+        assignee: { type: "string", description: "Filter by assignee agent" }
+      },
+      required: []
+    }
+  },
+  {
+    name: "claim_task",
+    description: "Claim a task for the current agent",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task_id: { type: "string", description: "Task ID (section UUID)" }
+      },
+      required: ["task_id"]
+    }
+  },
+  {
+    name: "complete_task",
+    description: "Mark a task as complete. Always pass output_artifact_id if you created an artifact. Always pass output_references listing every entity you created or touched.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task_id: { type: "string", description: "Task ID" },
+        output_text: { type: "string", description: "Completion summary / what was done" },
+        output_url: { type: "string", description: "URL to deliverable (PR, doc, etc.)" },
+        output_artifact_id: { type: "string", description: "UUID of the primary artifact produced by this task" },
+        output_references: {
+          type: "array",
+          description: "All entities created or interacted with: artifacts, tasks, agents, goals",
+          items: {
+            type: "object",
+            properties: {
+              type: { type: "string", description: "artifact | task | agent | goal" },
+              id: { type: "string", description: "Entity UUID" },
+              title: { type: "string", description: "Display name for the reference card" },
+              subtitle: { type: "string", description: "Optional: type label, status, role, etc." }
+            },
+            required: ["type", "id", "title"]
+          }
+        }
+      },
+      required: ["task_id"]
+    }
+  },
+  {
+    name: "block_task",
+    description: "Mark a task as blocked",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task_id: { type: "string", description: "Task ID" },
+        reason: { type: "string", description: "Why it is blocked" },
+        blocker_type: { type: "string", description: "Type: decision, dependency, resource, external" }
+      },
+      required: ["task_id", "reason"]
+    }
+  },
+  {
+    name: "report_progress",
+    description: 'Report what you are currently doing on a task. Call this at meaningful milestones so your work is visible in the platform (e.g., "Analyzed 12 PRs, now writing the summary section", "Completed API design, starting implementation"). This is how your progress appears to humans watching the work.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        task_id: { type: "string", description: "Task ID" },
+        message: { type: "string", description: "What you are doing right now \u2014 be specific and human-readable" },
+        metadata: { type: "object", description: "Optional extra context (step number, percentage, etc.)" }
+      },
+      required: ["task_id", "message"]
+    }
+  },
+  {
+    name: "create_task",
+    description: "Create a new task under a goal. Use this to create actionable tasks \u2014 NOT create_artifact or create_section.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        goal_id: { type: "string", description: "The goal UUID this task belongs to (required)" },
+        title: { type: "string", description: "Task title" },
+        description: { type: "string", description: "Task description / what needs to be done" },
+        priority: { type: "string", description: "Priority: low, medium, high, urgent" },
+        assigned_to: { type: "string", description: "Agent UUID to assign the task to" },
+        depends_on: { type: "array", items: { type: "string" }, description: "List of task UUIDs this task depends on" },
+        estimated_minutes: { type: "number", description: "Estimated time in minutes" }
+      },
+      required: ["goal_id", "title"]
+    }
+  },
+  // Agent tools
+  {
+    name: "list_agents",
+    description: "List all agents in the organization",
+    inputSchema: {
+      type: "object",
+      properties: {
+        status: { type: "string", description: "Filter by status: active, inactive" }
+      },
+      required: []
+    }
+  },
+  {
+    name: "get_agent",
+    description: "Get details about an agent",
+    inputSchema: {
+      type: "object",
+      properties: {
+        agent_id: { type: "string", description: "Agent ID" }
+      },
+      required: ["agent_id"]
+    }
+  },
+  {
+    name: "create_agent",
+    description: "Register a new AI agent with role, capabilities, and permissions",
+    inputSchema: {
+      type: "object",
+      properties: {
+        agentId: { type: "string", description: 'Unique agent ID (e.g., "engineering-agent", "qa-agent")' },
+        name: { type: "string", description: "Agent display name" },
+        role: { type: "string", description: "Role: pm, engineering, qa, research, content, design" },
+        description: { type: "string", description: "What this agent does - detailed description" },
+        capabilities: { type: "array", items: { type: "string" }, description: 'List of capabilities (e.g., ["code-review", "testing", "debugging"])' },
+        permissions: {
+          type: "object",
+          description: "Permission settings",
+          properties: {
+            write: { type: "boolean", description: "Can create/edit artifacts" },
+            delete: { type: "boolean", description: "Can delete artifacts" },
+            delegate_tasks: { type: "boolean", description: "Can assign tasks to other agents" }
+          }
+        },
+        systemPrompt: { type: "string", description: "System prompt for the agent" },
+        reportsToAgentId: { type: "string", description: 'Agent ID or UUID of the parent agent this agent reports to. Use agent slugs like "chief-of-staff" for readability.' }
+      },
+      required: ["agentId", "name", "role", "description"]
+    }
+  },
+  {
+    name: "update_agent",
+    description: "Update an agent",
+    inputSchema: {
+      type: "object",
+      properties: {
+        agent_id: { type: "string", description: "Agent ID" },
+        name: { type: "string", description: "New name" },
+        status: { type: "string", description: "New status" },
+        config: { type: "object", description: "Updated config" }
+      },
+      required: ["agent_id"]
+    }
+  },
+  // Inbox tools (human-in-the-loop)
+  {
+    name: "create_inbox_item",
+    description: "Request human approval, a decision, or an answer before proceeding. Automatically blocks the task. Use for agent creation, risky actions, or anything requiring human sign-off.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task_id: { type: "string", description: "UUID of the task being blocked (required)" },
+        type: { type: "string", description: "Type: approval, decision, question" },
+        title: { type: "string", description: "Short summary shown to the human in the inbox" },
+        content: { type: "string", description: "Full context and details for the human" },
+        action: { type: "string", description: "Action to auto-execute if approved (e.g. agent.create)" },
+        action_payload: { type: "object", description: "Data for the action (e.g. full agent spec for agent.create)" },
+        options: { type: "array", description: "Options for decision type: [{id, label, description}]" }
+      },
+      required: ["task_id", "type", "title"]
+    }
+  },
+  {
+    name: "list_inbox",
+    description: "List pending inbox items (approvals, decisions, questions) waiting for human resolution.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        status: { type: "string", description: "Filter by status: pending (default), resolved" },
+        type: { type: "string", description: "Filter by type: approval, decision, question" },
+        limit: { type: "number", description: "Max results (default 50)" }
+      },
+      required: []
+    }
+  },
+  {
+    name: "resolve_inbox",
+    description: "Resolve an inbox item from the agent side. Humans resolve via the UI \u2014 only use this for automated resolution.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        item_id: { type: "string", description: "Inbox item UUID" },
+        approved: { type: "boolean", description: "For approvals: true to approve, false to deny" },
+        chosen_option: { type: "string", description: "For decisions: the selected option ID" },
+        answer: { type: "string", description: "For questions: the answer text" },
+        notes: { type: "string", description: "Optional notes" }
+      },
+      required: ["item_id"]
+    }
+  },
+  // Search tools
+  {
+    name: "search_artifacts",
+    description: "Search artifacts by text query",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search query" },
+        type: { type: "string", description: "Filter by type" },
+        limit: { type: "number", description: "Max results" }
+      },
+      required: ["query"]
+    }
+  },
+  // Goal management
+  {
+    name: "update_goal",
+    description: "Update a goal's title, description, or status. Use when human feedback reveals the goal was based on wrong premises and needs to be corrected before re-planning.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        goal_id: { type: "string", description: "Goal UUID" },
+        title: { type: "string", description: "New title" },
+        description: { type: "string", description: "New description" },
+        status: { type: "string", description: "New status: active, completed, paused, cancelled" },
+        priority: { type: "string", description: "New priority: low, medium, high, urgent" }
+      },
+      required: ["goal_id"]
+    }
+  },
+  // Task cancellation
+  {
+    name: "cancel_task",
+    description: "Cancel and remove a task that should no longer be executed \u2014 e.g. because human feedback revealed it was based on wrong premises. Use alongside create_task to replace stale tasks with corrected ones.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task_id: { type: "string", description: "Task UUID to cancel" }
+      },
+      required: ["task_id"]
+    }
+  },
+  // Context tools
+  {
+    name: "get_task_context",
+    description: "Get full context for a task (org, project, artifact, related sections)",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task_id: { type: "string", description: "Task ID" }
+      },
+      required: ["task_id"]
+    }
+  }
+];
+var ArtyfactsApiClient = class {
+  constructor(baseUrl, apiKey, agentId) {
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+    this.agentId = agentId;
+  }
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      "Authorization": `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json"
+    };
+    if (this.agentId) {
+      headers["X-Agent-Id"] = this.agentId;
+    }
+    const response = await fetch(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : void 0
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: "Request failed" }));
+      throw new Error(error.error || `HTTP ${response.status}: ${response.statusText}`);
+    }
+    return response.json();
+  }
+  get(path) {
+    return this.request("GET", path);
+  }
+  getAgentId() {
+    return this.agentId;
+  }
+  post(path, body) {
+    return this.request("POST", path, body);
+  }
+  patch(path, body) {
+    return this.request("PATCH", path, body);
+  }
+  put(path, body) {
+    return this.request("PUT", path, body);
+  }
+  delete(path) {
+    return this.request("DELETE", path);
+  }
+};
+var toolHandlers = {
+  // Organization
+  get_organization: (client) => client.get("/org"),
+  // Projects
+  list_projects: (client, args) => {
+    const params = new URLSearchParams();
+    if (args.limit) params.set("limit", String(args.limit));
+    if (args.offset) params.set("offset", String(args.offset));
+    return client.get(`/projects?${params}`);
+  },
+  get_project: (client, args) => client.get(`/projects/${args.project_id}`),
+  // Artifacts
+  list_artifacts: (client, args) => {
+    const params = new URLSearchParams();
+    if (args.project_id) params.set("project_id", String(args.project_id));
+    if (args.type) params.set("type", String(args.type));
+    if (args.status) params.set("status", String(args.status));
+    if (args.limit) params.set("limit", String(args.limit));
+    return client.get(`/artifacts?${params}`);
+  },
+  get_artifact: (client, args) => client.get(`/artifacts/${args.artifact_id}`),
+  create_artifact: (client, args) => {
+    const envelope = {
+      aah_version: "0.3",
+      artifact: {
+        id: args.id || `artifact-${Date.now()}`,
+        title: args.title,
+        type: args.type || "document/sectioned",
+        artifact_type: args.artifact_type || args.type || "doc",
+        goal_id: args.goal_id,
+        parent_id: args.parent_id,
+        tags: args.tags
+      },
+      content: args.content ? {
+        media_type: "text/markdown",
+        body: args.content
+      } : void 0,
+      source: {
+        agent_id: client.getAgentId() || "mcp-agent"
+      }
+    };
+    return client.post("/artifacts", envelope);
+  },
+  update_artifact: (client, args) => {
+    const { artifact_id, ...body } = args;
+    return client.patch(`/artifacts/${artifact_id}`, body);
+  },
+  // Sections
+  list_sections: (client, args) => client.get(`/artifacts/${args.artifact_id}/sections`),
+  get_section: (client, args) => client.get(`/artifacts/${args.artifact_id}/sections/${args.section_id}`),
+  create_section: (client, args) => {
+    const { artifact_id, section_id, ...rest } = args;
+    const body = { id: section_id, ...rest };
+    return client.post(`/artifacts/${artifact_id}/sections`, body);
+  },
+  update_section: (client, args) => {
+    const { artifact_id, section_id, ...body } = args;
+    return client.patch(`/artifacts/${artifact_id}/sections/${section_id}`, body);
+  },
+  delete_section: (client, args) => client.delete(`/artifacts/${args.artifact_id}/sections/${args.section_id}`),
+  // Tasks
+  list_tasks: (client, args) => {
+    const params = new URLSearchParams();
+    if (args.artifact_id) params.set("artifact_id", String(args.artifact_id));
+    if (args.status) params.set("status", String(args.status));
+    if (args.assignee) params.set("assignee", String(args.assignee));
+    return client.get(`/tasks?${params}`);
+  },
+  claim_task: (client, args) => client.post(`/tasks/${args.task_id}/claim`),
+  complete_task: (client, args) => {
+    const { task_id, ...body } = args;
+    return client.post(`/tasks/${task_id}/complete`, body);
+  },
+  block_task: (client, args) => {
+    const { task_id, ...body } = args;
+    return client.post(`/tasks/${task_id}/block`, body);
+  },
+  report_progress: (client, args) => {
+    const { task_id, message, metadata } = args;
+    return client.post(`/tasks/${task_id}/activity`, {
+      type: "progress",
+      content: message,
+      metadata: metadata ?? {}
+    });
+  },
+  create_task: (client, args) => {
+    const { goal_id, title, description, priority, assigned_to, depends_on, estimated_minutes } = args;
+    return client.post("/tasks", { goal_id, title, description, priority, assigned_to, depends_on, estimated_minutes });
+  },
+  // Agents
+  list_agents: (client, args) => {
+    const params = new URLSearchParams();
+    if (args.status) params.set("status", String(args.status));
+    return client.get(`/agents?${params}`);
+  },
+  get_agent: (client, args) => client.get(`/agents/${args.agent_id}`),
+  create_agent: (client, args) => {
+    const body = {
+      agentId: args.agentId,
+      name: args.name,
+      role: args.role,
+      description: args.description,
+      reportsToAgentId: args.reportsToAgentId,
+      permissions: args.permissions || { write: true, delete: false, delegate_tasks: false },
+      metadata: {
+        capabilities: args.capabilities || [],
+        systemPrompt: args.systemPrompt,
+        createdVia: "mcp"
+      }
+    };
+    return client.post("/agents", body);
+  },
+  update_agent: (client, args) => {
+    const { agent_id, ...body } = args;
+    return client.patch(`/agents/${agent_id}`, body);
+  },
+  // Inbox (human-in-the-loop)
+  create_inbox_item: (client, args) => {
+    const { task_id, type, title, content, action, action_payload, options } = args;
+    return client.post("/inbox", { task_id, type, title, content, action, action_payload, options });
+  },
+  list_inbox: (client, args) => {
+    const params = new URLSearchParams();
+    if (args.status) params.set("status", String(args.status));
+    if (args.type) params.set("type", String(args.type));
+    if (args.limit) params.set("limit", String(args.limit));
+    return client.get(`/inbox?${params}`);
+  },
+  resolve_inbox: (client, args) => {
+    const { item_id, ...body } = args;
+    return client.post(`/inbox/${item_id}/resolve`, body);
+  },
+  // Goals
+  update_goal: (client, args) => {
+    const { goal_id, ...body } = args;
+    return client.put(`/goals/${goal_id}`, body);
+  },
+  // Task cancellation
+  cancel_task: (client, args) => client.delete(`/tasks/${args.task_id}`),
+  // Search
+  search_artifacts: (client, args) => {
+    const params = new URLSearchParams();
+    params.set("q", String(args.query));
+    if (args.type) params.set("type", String(args.type));
+    if (args.limit) params.set("limit", String(args.limit));
+    return client.get(`/search?${params}`);
+  },
+  // Context
+  get_task_context: (client, args) => client.get(`/tasks/${args.task_id}/context`)
+};
+var ArtyfactsMcpServer = class {
+  server;
+  client;
+  config;
+  constructor(config) {
+    this.config = config;
+    this.client = new ArtyfactsApiClient(
+      config.baseUrl || "https://artyfacts.dev/api/v1",
+      config.apiKey,
+      config.agentId
+    );
+    this.server = new Server(
+      {
+        name: config.name || "artyfacts-mcp",
+        version: config.version || "1.0.0"
+      },
+      {
+        capabilities: {
+          tools: {}
+        }
+      }
+    );
+    this.setupHandlers();
+  }
+  setupHandlers() {
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      return { tools: ARTYFACTS_TOOLS };
+    });
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+      const handler = toolHandlers[name];
+      if (!handler) {
+        return {
+          content: [{ type: "text", text: `Unknown tool: ${name}` }],
+          isError: true
+        };
+      }
+      try {
+        const result = await handler(this.client, args || {});
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    });
+  }
+  async start() {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+    console.error(`Artyfacts MCP server running (${ARTYFACTS_TOOLS.length} tools)`);
+  }
+  getServer() {
+    return this.server;
+  }
+};
+function createMcpServer(config) {
+  return new ArtyfactsMcpServer(config);
+}
+async function startServer(server) {
+  await server.start();
+}
+
+export {
+  ArtyfactsMcpServer,
+  createMcpServer,
+  startServer
+};