artifacty 0.2.0 → 0.4.0

package/src/mcp-server.js

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import path from "node:path";
 import readline from "node:readline";
+import { fileURLToPath } from "node:url";
 import {
   ARTIFACT_FORMATS,
   ARTIFACT_TYPES,
@@ -8,7 +11,7 @@ import {
   createStore,
   getArtifact,
   listAuditEvents,
-  listArtifacts,
+  listArtifactsPage,
   restoreArtifact,
   updateArtifact
 } from "./lib/storage.js";
@@ -16,6 +19,7 @@ import { convertAgentArtifact } from "./lib/converters.js";
 import { resolvePublicBaseUrl } from "./lib/server-state.js";
 
 const PROTOCOL_VERSION = "2025-06-18";
+const PACKAGE_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const store = createStore();
 
 const nativeArtifactInputSchema = {
@@ -86,7 +90,8 @@ const tools = [
         tag: { type: "string" },
         sourceAgent: { type: "string" },
         includeArchived: { type: "boolean" },
-        limit: { type: "number" }
+        limit: { type: "number" },
+        offset: { type: "number" }
       }
     },
     annotations: {
@@ -254,6 +259,71 @@ const tools = [
   }
 ];
 
+const resourceTemplates = [
+  {
+    uriTemplate: "artifacty://artifacts/{id}",
+    name: "artifact-by-id",
+    title: "Artifact by ID",
+    description: "Read an Artifacty artifact with metadata, latest version, content, and browser URLs.",
+    mimeType: "application/json"
+  },
+  {
+    uriTemplate: "artifacty://artifacts/{id}/raw{?version}",
+    name: "artifact-raw-content",
+    title: "Artifact Raw Content",
+    description: "Read raw artifact content by ID and optional version.",
+    mimeType: "text/plain"
+  }
+];
+
+const prompts = [
+  {
+    name: "artifacty_handoff",
+    title: "Create Artifact Handoff",
+    description: "Prepare a concise continuation artifact for another agent.",
+    arguments: [
+      { name: "goal", description: "Current goal or handoff objective.", required: false },
+      { name: "artifactId", description: "Existing Artifacty artifact to continue from.", required: false }
+    ]
+  },
+  {
+    name: "artifacty_review",
+    title: "Create Review Artifact",
+    description: "Capture code review findings as a shareable Artifacty artifact.",
+    arguments: [
+      { name: "scope", description: "Files, branch, PR, or behavior under review.", required: false },
+      { name: "artifactId", description: "Existing artifact with review context.", required: false }
+    ]
+  },
+  {
+    name: "artifacty_test_report",
+    title: "Create Test Report Artifact",
+    description: "Summarize verification commands, status, failures, and residual risk.",
+    arguments: [
+      { name: "goal", description: "Feature or release being verified.", required: false },
+      { name: "artifactId", description: "Existing artifact with implementation context.", required: false }
+    ]
+  },
+  {
+    name: "artifacty_visual_qa",
+    title: "Create Visual QA Artifact",
+    description: "Record browser, screenshot, media, or visual regression evidence.",
+    arguments: [
+      { name: "target", description: "URL, artifact ID, or UI surface under visual review.", required: false },
+      { name: "artifactId", description: "Existing visual evidence artifact.", required: false }
+    ]
+  },
+  {
+    name: "artifacty_release_notes",
+    title: "Create Release Notes Artifact",
+    description: "Draft release notes from changed artifacts, tests, and known risks.",
+    arguments: [
+      { name: "version", description: "Release version.", required: false },
+      { name: "artifactId", description: "Existing roadmap, checklist, or handoff artifact.", required: false }
+    ]
+  }
+];
+
 const rl = readline.createInterface({
   input: process.stdin,
   crlfDelay: Infinity
@@ -310,14 +380,21 @@ async function handleRequest(message) {
       capabilities: {
         tools: {
           listChanged: false
+        },
+        resources: {
+          subscribe: false,
+          listChanged: false
+        },
+        prompts: {
+          listChanged: false
         }
       },
       serverInfo: {
         name: "artifacty",
         title: "Artifacty",
-        version: "0.1.0"
+        version: "0.4.0"
       },
-      instructions: "Use Artifacty to create, import, list, read, and update local artifacts that other agents can reuse."
+      instructions: "Use Artifacty to create, import, list, read, update, and resource-read local artifacts that other agents can reuse."
     };
   }
 
@@ -334,6 +411,27 @@ async function handleRequest(message) {
     return callTool(params.name, params.arguments || {});
   }
 
+  if (message.method === "resources/list") {
+    return listResources();
+  }
+
+  if (message.method === "resources/templates/list") {
+    return { resourceTemplates };
+  }
+
+  if (message.method === "resources/read") {
+    return readResource(requireParam(message.params, "uri"));
+  }
+
+  if (message.method === "prompts/list") {
+    return { prompts };
+  }
+
+  if (message.method === "prompts/get") {
+    const params = message.params || {};
+    return getPrompt(requireParam(params, "name"), params.arguments || {});
+  }
+
   throw Object.assign(new Error(`Method not found: ${message.method}`), {
     jsonRpcCode: -32601
   });
@@ -346,12 +444,21 @@ async function callTool(name, args) {
 
   if (name === "artifacty_list") {
     const publicBaseUrl = await resolvePublicBaseUrl(store);
-    const artifacts = await listArtifacts(store, args);
+    const page = await listArtifactsPage(store, args);
     return toolResult({
-      artifacts: artifacts.map((artifact) => ({
+      artifacts: page.artifacts.map((artifact) => ({
         ...artifact,
         url: `${publicBaseUrl}/artifacts/${encodeURIComponent(artifact.id)}`
-      }))
+      })),
+      pagination: {
+        total: page.total,
+        limit: page.limit,
+        offset: page.offset,
+        hasMore: page.hasMore,
+        nextOffset: page.nextOffset,
+        previousOffset: page.previousOffset
+      },
+      search: page.search
     });
   }
 
@@ -430,6 +537,177 @@ async function callTool(name, args) {
   });
 }
 
+async function listResources() {
+  const page = await listArtifactsPage(store, { limit: 10 });
+  const artifactResources = page.artifacts.flatMap((artifact) => [
+    {
+      uri: artifactResourceUri(artifact.id),
+      name: `artifact:${artifact.id}`,
+      title: artifact.title,
+      description: `${artifact.sourceAgent} ${artifact.artifactType} artifact, v${artifact.latestVersion}`,
+      mimeType: "application/json"
+    },
+    {
+      uri: artifactRawResourceUri(artifact.id),
+      name: `artifact-raw:${artifact.id}`,
+      title: `${artifact.title} raw`,
+      description: `Raw latest ${artifact.format || "text"} content for ${artifact.id}`,
+      mimeType: artifact.contentType || "text/plain"
+    }
+  ]);
+
+  return {
+    resources: [
+      {
+        uri: "artifacty://recent",
+        name: "recent-artifacts",
+        title: "Recent Artifacts",
+        description: "Recent Artifacty artifacts with pagination metadata and browser URLs.",
+        mimeType: "application/json"
+      },
+      {
+        uri: "artifacty://schema/v1",
+        name: "artifact-schema-v1",
+        title: "Artifact Schema v1",
+        description: "Artifacty schema v1 reference document.",
+        mimeType: "text/markdown"
+      },
+      ...artifactResources
+    ]
+  };
+}
+
+async function readResource(uri) {
+  if (uri === "artifacty://recent") {
+    const publicBaseUrl = await resolvePublicBaseUrl(store);
+    const page = await listArtifactsPage(store, { limit: 20 });
+    return resourceText(uri, "application/json", {
+      artifacts: page.artifacts.map((artifact) => ({
+        ...artifact,
+        url: `${publicBaseUrl}/artifacts/${encodeURIComponent(artifact.id)}`
+      })),
+      pagination: {
+        total: page.total,
+        limit: page.limit,
+        offset: page.offset,
+        hasMore: page.hasMore,
+        nextOffset: page.nextOffset,
+        previousOffset: page.previousOffset
+      },
+      search: page.search
+    });
+  }
+
+  if (uri === "artifacty://schema/v1") {
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "text/markdown",
+          text: await readFile(path.join(PACKAGE_ROOT, "docs", "artifact-schema-v1.md"), "utf8")
+        }
+      ]
+    };
+  }
+
+  const parsed = parseArtifactResourceUri(uri);
+  if (parsed) {
+    const artifact = await getArtifact(store, parsed.id, {
+      version: parsed.version,
+      audit: mcpAuditContext()
+    });
+    if (parsed.raw) {
+      return {
+        contents: [
+          {
+            uri,
+            mimeType: artifact.version.contentType || "text/plain",
+            text: artifact.content
+          }
+        ]
+      };
+    }
+    return resourceText(uri, "application/json", await withUrls(artifact));
+  }
+
+  throw Object.assign(new Error(`Unknown resource: ${uri}`), {
+    jsonRpcCode: -32602
+  });
+}
+
+function getPrompt(name, args) {
+  const definition = prompts.find((prompt) => prompt.name === name);
+  if (!definition) {
+    throw Object.assign(new Error(`Unknown prompt: ${name}`), {
+      jsonRpcCode: -32602
+    });
+  }
+
+  return {
+    description: definition.description,
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: promptText(name, args)
+        }
+      }
+    ]
+  };
+}
+
+function promptText(name, args = {}) {
+  const context = args.artifactId
+    ? `First read Artifacty resource ${artifactResourceUri(args.artifactId)} and use it as context.`
+    : "Use the current session context and any relevant Artifacty resources.";
+  const common = `${context}
+
+Create or update an Artifacty artifact through artifacty_create, artifacty_import, or artifacty_update. Use concise Markdown unless another format is clearly better. Include sourceAgent, artifactType, and tags so another agent can discover it.`;
+
+  if (name === "artifacty_handoff") {
+    return `${common}
+
+Goal: ${args.goal || "Prepare a continuation handoff for the next agent."}
+
+Capture: current state, changed files or artifacts, commands run, decisions, blockers, residual risk, and next steps.
+Recommended artifactType: handoff. Recommended tags: handoff, continuation.`;
+  }
+  if (name === "artifacty_review") {
+    return `${common}
+
+Review scope: ${args.scope || "Review the current implementation or linked artifact."}
+
+Capture findings first, ordered by severity, with file/line references when available. Include open questions and verification gaps.
+Recommended artifactType: code-review. Recommended tags: review.`;
+  }
+  if (name === "artifacty_test_report") {
+    return `${common}
+
+Verification goal: ${args.goal || "Summarize test and smoke evidence."}
+
+Capture commands, status, failures, environment, manual checks, and what remains untested.
+Recommended artifactType: test-report. Recommended tags: verification, test-report.`;
+  }
+  if (name === "artifacty_visual_qa") {
+    return `${common}
+
+Visual target: ${args.target || "Inspect the UI or visual artifact under review."}
+
+Capture screenshots/media references, viewport, expected behavior, observed issues, and pass/fail verdict.
+Recommended artifactType: design-option or bundle. Recommended tags: visual, qa.`;
+  }
+  if (name === "artifacty_release_notes") {
+    return `${common}
+
+Release version: ${args.version || "next"}
+
+Capture highlights, breaking changes, migration notes, tests, known limitations, and publish evidence.
+Recommended artifactType: document. Recommended tags: release-notes.`;
+  }
+  return common;
+}
+
 async function createNativeArtifact(args) {
   return createArtifact(store, {
     title: args.title,
@@ -461,6 +739,49 @@ async function withUrls(artifact) {
   };
 }
 
+function resourceText(uri, mimeType, data) {
+  return {
+    contents: [
+      {
+        uri,
+        mimeType,
+        text: typeof data === "string" ? data : JSON.stringify(data, null, 2)
+      }
+    ]
+  };
+}
+
+function artifactResourceUri(id) {
+  return `artifacty://artifacts/${encodeURIComponent(id)}`;
+}
+
+function artifactRawResourceUri(id, version) {
+  const suffix = version ? `?version=${encodeURIComponent(String(version))}` : "";
+  return `artifacty://artifacts/${encodeURIComponent(id)}/raw${suffix}`;
+}
+
+function parseArtifactResourceUri(uri) {
+  let parsed;
+  try {
+    parsed = new URL(uri);
+  } catch {
+    return null;
+  }
+
+  if (parsed.protocol !== "artifacty:" || parsed.hostname !== "artifacts") {
+    return null;
+  }
+  const parts = parsed.pathname.split("/").filter(Boolean);
+  if (parts.length !== 1 && !(parts.length === 2 && parts[1] === "raw")) {
+    return null;
+  }
+  return {
+    id: decodeURIComponent(parts[0]),
+    raw: parts[1] === "raw",
+    version: parsed.searchParams.get("version") || undefined
+  };
+}
+
 function toolResult(data) {
   return {
     content: [
@@ -483,6 +804,15 @@ function requireArg(args, name) {
   return args[name];
 }
 
+function requireParam(params = {}, name) {
+  if (!params[name]) {
+    throw Object.assign(new Error(`Missing required parameter: ${name}`), {
+      jsonRpcCode: -32602
+    });
+  }
+  return params[name];
+}
+
 function writeResponse(id, result, error) {
   const response = {
     jsonrpc: "2.0",

package/src/server.js

@@ -9,7 +9,7 @@ import {
   createArtifact,
   createStore,
   getArtifact,
-  listArtifacts,
+  listArtifactsPage,
   listAuditEvents,
   MAX_ARTIFACT_BYTES,
   restoreArtifact,
@@ -177,15 +177,19 @@ export async function handleRequest({ request, response, store, host, port, secu
       query: url.searchParams.get("q") || "",
       tag: url.searchParams.get("tag") || "",
       sourceAgent: url.searchParams.get("sourceAgent") || "",
-      includeArchived: url.searchParams.get("includeArchived") === "true"
+      includeArchived: url.searchParams.get("includeArchived") === "true",
+      limit: url.searchParams.get("limit") || undefined,
+      offset: url.searchParams.get("offset") || undefined
     };
-    const artifacts = await listArtifacts(store, {
+    const page = await listArtifactsPage(store, {
       query: filters.query || undefined,
       tag: filters.tag || undefined,
       sourceAgent: filters.sourceAgent || undefined,
-      includeArchived: filters.includeArchived
+      includeArchived: filters.includeArchived,
+      limit: filters.limit,
+      offset: filters.offset
     });
-    return sendHtml(response, renderDashboard({ artifacts, baseUrl, filters, locale, currentPath }), 200, headOnly);
+    return sendHtml(response, renderDashboard({ artifacts: page.artifacts, baseUrl, filters, pagination: page, locale, currentPath }), 200, headOnly);
   }
 
   if (method === "GET" && pathname === "/new") {
@@ -240,14 +244,19 @@ export async function handleRequest({ request, response, store, host, port, secu
   }
 
   if (method === "GET" && pathname === "/api/artifacts") {
-    const artifacts = await listArtifacts(store, {
+    const page = await listArtifactsPage(store, {
       query: url.searchParams.get("q") || undefined,
       tag: url.searchParams.get("tag") || undefined,
       sourceAgent: url.searchParams.get("sourceAgent") || undefined,
       includeArchived: url.searchParams.get("includeArchived") === "true",
-      limit: url.searchParams.get("limit") || undefined
+      limit: url.searchParams.get("limit") || undefined,
+      offset: url.searchParams.get("offset") || undefined
     });
-    return sendJson(response, { artifacts }, 200, headOnly);
+    return sendJson(response, {
+      artifacts: page.artifacts,
+      pagination: paginationJson(page),
+      search: page.search
+    }, 200, headOnly);
   }
 
   if (method === "GET" && pathname === "/api/audit") {
@@ -442,6 +451,17 @@ export function decorateArtifactUrls(artifact, baseUrl) {
   };
 }
 
+function paginationJson(page) {
+  return {
+    total: page.total,
+    limit: page.limit,
+    offset: page.offset,
+    hasMore: page.hasMore,
+    nextOffset: page.nextOffset,
+    previousOffset: page.previousOffset
+  };
+}
+
 export async function readJsonBody(request) {
   const raw = await readBody(request, MAX_ARTIFACT_BYTES + 1024);
   if (!raw.trim()) {