@artyfacts/mcp-server 1.1.2 → 1.1.4

package/bin/artyfacts-mcp.js

@@ -5,6 +5,7 @@ import { createMcpServer, startServer } from '../dist/index.js';
 // Get config from environment or args
 const apiKey = process.env.ARTYFACTS_API_KEY;
 const baseUrl = process.env.ARTYFACTS_BASE_URL || 'https://artyfacts.dev/api/v1';
+const agentId = process.env.ARTYFACTS_AGENT_ID;
 
 if (!apiKey) {
   console.error('Error: ARTYFACTS_API_KEY environment variable is required');
@@ -20,6 +21,7 @@ if (!apiKey) {
 const server = createMcpServer({
   apiKey,
   baseUrl,
+  agentId,
 });
 
 startServer(server).catch((error) => {

package/dist/chunk-GOOQPNGV.js

@@ -0,0 +1,631 @@
+// 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" },
+        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",
+        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

@@ -313,7 +313,8 @@ var ARTYFACTS_TOOLS = [
             delegate_tasks: { type: "boolean", description: "Can assign tasks to other agents" }
           }
         },
-        systemPrompt: { type: "string", description: "System prompt for the agent" }
+        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"]
     }
@@ -406,18 +407,23 @@ var ARTYFACTS_TOOLS = [
   }
 ];
 var ArtyfactsApiClient = class {
-  constructor(baseUrl, apiKey) {
+  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: {
-        "Authorization": `Bearer ${this.apiKey}`,
-        "Content-Type": "application/json"
-      },
+      headers,
       body: body ? JSON.stringify(body) : void 0
     });
     if (!response.ok) {
@@ -429,6 +435,9 @@ var ArtyfactsApiClient = class {
   get(path) {
     return this.request("GET", path);
   }
+  getAgentId() {
+    return this.agentId;
+  }
   post(path, body) {
     return this.request("POST", path, body);
   }
@@ -476,7 +485,7 @@ var toolHandlers = {
         body: args.content
       } : void 0,
       source: {
-        agent_id: "mcp-agent"
+        agent_id: client.getAgentId() || "mcp-agent"
       }
     };
     return client.post("/artifacts", envelope);
@@ -532,6 +541,7 @@ var toolHandlers = {
       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 || [],
@@ -580,7 +590,8 @@ var ArtyfactsMcpServer = class {
     this.config = config;
     this.client = new ArtyfactsApiClient(
       config.baseUrl || "https://artyfacts.dev/api/v1",
-      config.apiKey
+      config.apiKey,
+      config.agentId
     );
     this.server = new import_server.Server(
       {

package/dist/index.js

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

package/dist/server.cjs

@@ -311,7 +311,8 @@ var ARTYFACTS_TOOLS = [
             delegate_tasks: { type: "boolean", description: "Can assign tasks to other agents" }
           }
         },
-        systemPrompt: { type: "string", description: "System prompt for the agent" }
+        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"]
     }
@@ -404,18 +405,23 @@ var ARTYFACTS_TOOLS = [
   }
 ];
 var ArtyfactsApiClient = class {
-  constructor(baseUrl, apiKey) {
+  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: {
-        "Authorization": `Bearer ${this.apiKey}`,
-        "Content-Type": "application/json"
-      },
+      headers,
       body: body ? JSON.stringify(body) : void 0
     });
     if (!response.ok) {
@@ -427,6 +433,9 @@ var ArtyfactsApiClient = class {
   get(path) {
     return this.request("GET", path);
   }
+  getAgentId() {
+    return this.agentId;
+  }
   post(path, body) {
     return this.request("POST", path, body);
   }
@@ -474,7 +483,7 @@ var toolHandlers = {
         body: args.content
       } : void 0,
       source: {
-        agent_id: "mcp-agent"
+        agent_id: client.getAgentId() || "mcp-agent"
       }
     };
     return client.post("/artifacts", envelope);
@@ -530,6 +539,7 @@ var toolHandlers = {
       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 || [],
@@ -578,7 +588,8 @@ var ArtyfactsMcpServer = class {
     this.config = config;
     this.client = new ArtyfactsApiClient(
       config.baseUrl || "https://artyfacts.dev/api/v1",
-      config.apiKey
+      config.apiKey,
+      config.agentId
     );
     this.server = new import_server.Server(
       {

package/dist/server.d.cts

@@ -12,6 +12,8 @@ interface McpServerConfig {
     apiKey: string;
     /** Artyfacts API base URL */
     baseUrl?: string;
+    /** Agent slug (e.g. 'chief-of-staff') — used to attribute writes to the correct agent */
+    agentId?: string;
     /** Server name */
     name?: string;
     /** Server version */

package/dist/server.d.ts

@@ -12,6 +12,8 @@ interface McpServerConfig {
     apiKey: string;
     /** Artyfacts API base URL */
     baseUrl?: string;
+    /** Agent slug (e.g. 'chief-of-staff') — used to attribute writes to the correct agent */
+    agentId?: string;
     /** Server name */
     name?: string;
     /** Server version */

package/dist/server.js

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

package/package.json

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

package/src/server.ts

@@ -22,6 +22,8 @@ export interface McpServerConfig {
   apiKey: string;
   /** Artyfacts API base URL */
   baseUrl?: string;
+  /** Agent slug (e.g. 'chief-of-staff') — used to attribute writes to the correct agent */
+  agentId?: string;
   /** Server name */
   name?: string;
   /** Server version */
@@ -321,6 +323,7 @@ const ARTYFACTS_TOOLS: Tool[] = [
           }
         },
         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'],
     },
@@ -423,18 +426,24 @@ const ARTYFACTS_TOOLS: Tool[] = [
 class ArtyfactsApiClient {
   constructor(
     private baseUrl: string,
-    private apiKey: string
+    private apiKey: string,
+    private agentId?: string
   ) {}
 
   async request(method: string, path: string, body?: unknown): Promise<unknown> {
     const url = `${this.baseUrl}${path}`;
-    
+
+    const headers: Record<string, string> = {
+      'Authorization': `Bearer ${this.apiKey}`,
+      'Content-Type': 'application/json',
+    };
+    if (this.agentId) {
+      headers['X-Agent-Id'] = this.agentId;
+    }
+
     const response = await fetch(url, {
       method,
-      headers: {
-        'Authorization': `Bearer ${this.apiKey}`,
-        'Content-Type': 'application/json',
-      },
+      headers,
       body: body ? JSON.stringify(body) : undefined,
     });
 
@@ -447,6 +456,7 @@ class ArtyfactsApiClient {
   }
 
   get(path: string) { return this.request('GET', path); }
+  getAgentId() { return this.agentId; }
   post(path: string, body?: unknown) { return this.request('POST', path, body); }
   patch(path: string, body?: unknown) { return this.request('PATCH', path, body); }
   delete(path: string) { return this.request('DELETE', path); }
@@ -498,7 +508,7 @@ const toolHandlers: Record<string, ToolHandler> = {
         body: args.content,
       } : undefined,
       source: {
-        agent_id: 'mcp-agent',
+        agent_id: client.getAgentId() || 'mcp-agent',
       },
     };
     return client.post('/artifacts', envelope);
@@ -559,6 +569,7 @@ const toolHandlers: Record<string, ToolHandler> = {
       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 || [],
@@ -616,7 +627,8 @@ export class ArtyfactsMcpServer {
     this.config = config;
     this.client = new ArtyfactsApiClient(
       config.baseUrl || 'https://artyfacts.dev/api/v1',
-      config.apiKey
+      config.apiKey,
+      config.agentId
     );
 
     this.server = new Server(