@artyfacts/mcp-server 1.0.2 → 1.0.3

package/dist/chunk-VCIOVYRM.js

@@ -0,0 +1,556 @@
+// 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",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task_id: { type: "string", description: "Task ID" },
+        output_url: { type: "string", description: "URL to deliverable (PR, doc, etc.)" },
+        summary: { type: "string", description: "Completion summary" }
+      },
+      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"]
+    }
+  },
+  // 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 agent",
+    inputSchema: {
+      type: "object",
+      properties: {
+        agentId: { type: "string", description: 'Unique agent ID (e.g., "engineering-agent", "qa-agent")' },
+        name: { type: "string", description: "Agent display name" },
+        type: { type: "string", description: "Type: pm, engineering, qa, research, content, design" },
+        description: { type: "string", description: "What this agent does" },
+        capabilities: { type: "array", items: { type: "string" }, description: "Agent capabilities" },
+        config: { type: "object", description: "Agent configuration" }
+      },
+      required: ["agentId", "name", "type"]
+    }
+  },
+  {
+    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"]
+    }
+  },
+  // Blocker tools
+  {
+    name: "list_blockers",
+    description: "List blockers (decisions, dependencies needing resolution)",
+    inputSchema: {
+      type: "object",
+      properties: {
+        artifact_id: { type: "string", description: "Filter by artifact" },
+        status: { type: "string", description: "Filter by status: open, resolved" }
+      },
+      required: []
+    }
+  },
+  {
+    name: "create_blocker",
+    description: "Create a blocker (decision request, dependency, etc.)",
+    inputSchema: {
+      type: "object",
+      properties: {
+        artifact_id: { type: "string", description: "Artifact ID" },
+        kind: { type: "string", description: "Kind: decision, dependency, resource, external" },
+        title: { type: "string", description: "Blocker title" },
+        description: { type: "string", description: "Details" },
+        options: { type: "array", description: "Options for decisions" },
+        blocked_tasks: { type: "array", items: { type: "string" }, description: "Task IDs blocked by this" }
+      },
+      required: ["artifact_id", "kind", "title"]
+    }
+  },
+  {
+    name: "resolve_blocker",
+    description: "Resolve a blocker",
+    inputSchema: {
+      type: "object",
+      properties: {
+        blocker_id: { type: "string", description: "Blocker ID" },
+        resolution: { type: "string", description: "How it was resolved" },
+        selected_option: { type: "string", description: "Selected option (for decisions)" }
+      },
+      required: ["blocker_id", "resolution"]
+    }
+  },
+  // 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) {
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+  }
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const response = await fetch(url, {
+      method,
+      headers: {
+        "Authorization": `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json"
+      },
+      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);
+  }
+  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: "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);
+  },
+  // 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) => client.post("/agents", args),
+  update_agent: (client, args) => {
+    const { agent_id, ...body } = args;
+    return client.patch(`/agents/${agent_id}`, body);
+  },
+  // Blockers
+  list_blockers: (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));
+    return client.get(`/blockers?${params}`);
+  },
+  create_blocker: (client, args) => {
+    const { artifact_id, ...body } = args;
+    return client.post(`/artifacts/${artifact_id}/blockers`, body);
+  },
+  resolve_blocker: (client, args) => {
+    const { blocker_id, ...body } = args;
+    return client.post(`/blockers/${blocker_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
+    );
+    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

@@ -93,18 +93,17 @@ var ARTYFACTS_TOOLS = [
   },
   {
     name: "create_artifact",
-    description: "Create a new artifact",
+    description: "Create a new artifact (document, goal, spec, etc.)",
     inputSchema: {
       type: "object",
       properties: {
         title: { type: "string", description: "Artifact title" },
-        type: { type: "string", description: "Type: goal, spec, research, report, experiment, decision" },
+        type: { type: "string", description: "Artifact type: goal, spec, research, report, experiment, decision, doc" },
         content: { type: "string", description: "Markdown content" },
-        project_id: { type: "string", description: "Project ID" },
-        parent_id: { type: "string", description: "Parent artifact ID" },
-        tags: { type: "array", items: { type: "string" }, description: "Tags" }
+        parent_id: { type: "string", description: "Parent artifact ID for nested artifacts" },
+        tags: { type: "array", items: { type: "string" }, description: "Tags for categorization" }
       },
-      required: ["title"]
+      required: ["title", "type"]
     }
   },
   {
@@ -158,7 +157,7 @@ var ARTYFACTS_TOOLS = [
         type: { type: "string", description: "Type: content, task, decision, blocker" },
         position: { type: "number", description: "Order position" }
       },
-      required: ["artifact_id", "section_id", "heading"]
+      required: ["artifact_id", "section_id", "heading", "content"]
     }
   },
   {
@@ -416,7 +415,27 @@ var toolHandlers = {
     return client.get(`/artifacts?${params}`);
   },
   get_artifact: (client, args) => client.get(`/artifacts/${args.artifact_id}`),
-  create_artifact: (client, args) => client.post("/artifacts", args),
+  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: "mcp-agent"
+      }
+    };
+    return client.post("/artifacts", envelope);
+  },
   update_artifact: (client, args) => {
     const { artifact_id, ...body } = args;
     return client.patch(`/artifacts/${artifact_id}`, body);
@@ -425,7 +444,8 @@ var toolHandlers = {
   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, ...body } = 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) => {

package/dist/index.js

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

package/dist/server.cjs

@@ -91,18 +91,17 @@ var ARTYFACTS_TOOLS = [
   },
   {
     name: "create_artifact",
-    description: "Create a new artifact",
+    description: "Create a new artifact (document, goal, spec, etc.)",
     inputSchema: {
       type: "object",
       properties: {
         title: { type: "string", description: "Artifact title" },
-        type: { type: "string", description: "Type: goal, spec, research, report, experiment, decision" },
+        type: { type: "string", description: "Artifact type: goal, spec, research, report, experiment, decision, doc" },
         content: { type: "string", description: "Markdown content" },
-        project_id: { type: "string", description: "Project ID" },
-        parent_id: { type: "string", description: "Parent artifact ID" },
-        tags: { type: "array", items: { type: "string" }, description: "Tags" }
+        parent_id: { type: "string", description: "Parent artifact ID for nested artifacts" },
+        tags: { type: "array", items: { type: "string" }, description: "Tags for categorization" }
       },
-      required: ["title"]
+      required: ["title", "type"]
     }
   },
   {
@@ -156,7 +155,7 @@ var ARTYFACTS_TOOLS = [
         type: { type: "string", description: "Type: content, task, decision, blocker" },
         position: { type: "number", description: "Order position" }
       },
-      required: ["artifact_id", "section_id", "heading"]
+      required: ["artifact_id", "section_id", "heading", "content"]
     }
   },
   {
@@ -414,7 +413,27 @@ var toolHandlers = {
     return client.get(`/artifacts?${params}`);
   },
   get_artifact: (client, args) => client.get(`/artifacts/${args.artifact_id}`),
-  create_artifact: (client, args) => client.post("/artifacts", args),
+  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: "mcp-agent"
+      }
+    };
+    return client.post("/artifacts", envelope);
+  },
   update_artifact: (client, args) => {
     const { artifact_id, ...body } = args;
     return client.patch(`/artifacts/${artifact_id}`, body);
@@ -423,7 +442,8 @@ var toolHandlers = {
   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, ...body } = 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) => {

package/dist/server.js

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

package/package.json

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

package/src/server.ts

@@ -97,18 +97,17 @@ const ARTYFACTS_TOOLS: Tool[] = [
   },
   {
     name: 'create_artifact',
-    description: 'Create a new artifact',
+    description: 'Create a new artifact (document, goal, spec, etc.)',
     inputSchema: {
       type: 'object',
       properties: {
         title: { type: 'string', description: 'Artifact title' },
-        type: { type: 'string', description: 'Type: goal, spec, research, report, experiment, decision' },
+        type: { type: 'string', description: 'Artifact type: goal, spec, research, report, experiment, decision, doc' },
         content: { type: 'string', description: 'Markdown content' },
-        project_id: { type: 'string', description: 'Project ID' },
-        parent_id: { type: 'string', description: 'Parent artifact ID' },
-        tags: { type: 'array', items: { type: 'string' }, description: 'Tags' },
+        parent_id: { type: 'string', description: 'Parent artifact ID for nested artifacts' },
+        tags: { type: 'array', items: { type: 'string' }, description: 'Tags for categorization' },
       },
-      required: ['title'],
+      required: ['title', 'type'],
     },
   },
   {
@@ -163,7 +162,7 @@ const ARTYFACTS_TOOLS: Tool[] = [
         type: { type: 'string', description: 'Type: content, task, decision, blocker' },
         position: { type: 'number', description: 'Order position' },
       },
-      required: ['artifact_id', 'section_id', 'heading'],
+      required: ['artifact_id', 'section_id', 'heading', 'content'],
     },
   },
   {
@@ -437,7 +436,28 @@ const toolHandlers: Record<string, ToolHandler> = {
     return client.get(`/artifacts?${params}`);
   },
   get_artifact: (client, args) => client.get(`/artifacts/${args.artifact_id}`),
-  create_artifact: (client, args) => client.post('/artifacts', args),
+  create_artifact: (client, args) => {
+    // API expects AAH envelope format
+    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,
+      } : undefined,
+      source: {
+        agent_id: 'mcp-agent',
+      },
+    };
+    return client.post('/artifacts', envelope);
+  },
   update_artifact: (client, args) => {
     const { artifact_id, ...body } = args;
     return client.patch(`/artifacts/${artifact_id}`, body);
@@ -447,7 +467,9 @@ const toolHandlers: Record<string, ToolHandler> = {
   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, ...body } = args;
+    const { artifact_id, section_id, ...rest } = args;
+    // API expects 'id' not 'section_id'
+    const body = { id: section_id, ...rest };
     return client.post(`/artifacts/${artifact_id}/sections`, body);
   },
   update_section: (client, args) => {