@artyfacts/mcp-server 1.1.4 → 1.1.5

package/dist/chunk-TEUGXQOH.js

@@ -0,0 +1,633 @@
+// 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: "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"]
+    }
+  },
+  // 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);
+  }
+  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);
+  },
+  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);
+  },
+  // 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
+};

package/dist/index.cjs

@@ -100,6 +100,7 @@ var ARTYFACTS_TOOLS = [
         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" }
       },
@@ -477,6 +478,7 @@ var toolHandlers = {
         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
       },

package/dist/index.js

@@ -2,7 +2,7 @@ import {
   ArtyfactsMcpServer,
   createMcpServer,
   startServer
-} from "./chunk-GOOQPNGV.js";
+} from "./chunk-TEUGXQOH.js";
 export {
   ArtyfactsMcpServer,
   createMcpServer,

package/dist/server.cjs

@@ -98,6 +98,7 @@ var ARTYFACTS_TOOLS = [
         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" }
       },
@@ -475,6 +476,7 @@ var toolHandlers = {
         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
       },

package/dist/server.js

@@ -2,7 +2,7 @@ import {
   ArtyfactsMcpServer,
   createMcpServer,
   startServer
-} from "./chunk-GOOQPNGV.js";
+} from "./chunk-TEUGXQOH.js";
 export {
   ArtyfactsMcpServer,
   createMcpServer,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@artyfacts/mcp-server",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "MCP server exposing Artyfacts tools for Claude Code",
   "type": "module",
   "main": "dist/index.js",

package/src/server.ts

@@ -106,6 +106,7 @@ const ARTYFACTS_TOOLS: Tool[] = [
         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 — 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' },
       },
@@ -500,6 +501,7 @@ const toolHandlers: Record<string, ToolHandler> = {
         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,
       },