artifacty 0.2.0 → 0.4.0

package/AGENTS.md

@@ -23,6 +23,8 @@ Artifacty shares LLM artifacts over HTTP, CLI, and MCP.
 - `node src/cli.js import --agent claude --file artifact.html`: convert and store an external artifact.
 - `node src/cli.js install claude --dry-run`: preview generated MCP config.
 - `node src/cli.js check`: verify MCP tool discovery.
+- `node src/cli.js index rebuild`: rebuild the optional SQLite FTS5 search index.
+- `node src/cli.js integrity`: verify version files, hashes, and orphaned files.
 
 ## Coding Style & Naming Conventions
 

package/README.md

@@ -165,6 +165,7 @@ List artifacts:
 
 ```bash
 artifacty list
+artifacty list --query review --limit 20 --offset 20
 ```
 
 Run the MCP server:
@@ -174,11 +175,17 @@ artifacty-mcp
 ```
 
 MCP clients can create artifacts with `artifacty_create`. `artifacty_publish` remains as a backwards-compatible alias.
+MCP clients that support resources or prompts can also read `artifacty://recent`,
+`artifacty://artifacts/{id}`, `artifacty://artifacts/{id}/raw{?version}`, and
+`artifacty://schema/v1`, or use prompt templates such as `artifacty_handoff`,
+`artifacty_review`, and `artifacty_release_notes`.
 
 Operational commands:
 
 ```bash
 artifacty audit --limit 20
+artifacty index rebuild
+artifacty integrity
 artifacty backup
 artifacty export --file ./artifacty-backup.json
 artifacty import-store --file ./artifacty-backup.json
@@ -200,6 +207,13 @@ ARTIFACTY_HOME=/path/to/shared/store artifacty serve
 
 Artifact metadata is stored in `artifacty.sqlite`; artifact content is stored as immutable version files under `artifacts/`. The current browser server URL is written to `server.json` so MCP tools can return the correct links when the default port falls back. Existing `index.json` stores are migrated automatically on first access.
 
+Search uses a SQLite FTS5 index when the local Node SQLite build supports it. The index covers the latest version body plus title, tags, source agent, artifact type, format, and metadata summary. If FTS5 is unavailable, Artifacty keeps working with metadata search. Rebuild or check the store when needed:
+
+```bash
+artifacty index rebuild
+artifacty integrity
+```
+
 ## API Example
 
 Start a protected server in another terminal, or generate a reusable shell token first:
@@ -245,6 +259,13 @@ Browser routes:
 - `/artifacts/:id/diff`: compare versions.
 - `/api/audit`: list audit events.
 
+List APIs support pagination with `limit` and `offset`. Responses keep the top-level `artifacts` array and include `pagination` and `search` metadata:
+
+```bash
+curl -s "http://127.0.0.1:8787/api/artifacts?q=handoff&limit=20&offset=0" \
+  -H "x-artifacty-token: $ARTIFACTY_API_TOKEN"
+```
+
 ## Interface Language
 
 The browser UI defaults to English. Add `?lang=ko` to any browser route to use Korean, for example `http://127.0.0.1:8787/new?lang=ko`. Forms and in-app links preserve the selected language. Documentation is maintained in English only.
@@ -258,6 +279,7 @@ Schema and storage:
 - Diagram, component, source snippet, analysis report, table, and media assets use `diagram`, `component`, `snippet`, `analysis-report`, `table`, and `asset` artifact types.
 - Copilot/Cursor examples cover PR reviews, screenshots, demo recordings, and visual evidence bundles.
 - See [docs/artifact-schema-v1.md](docs/artifact-schema-v1.md).
+- See [docs/mcp-public-api.md](docs/mcp-public-api.md) for MCP tools, resources, prompts, and compatibility notes.
 - See [docs/sarif-csv-artifact-plan.md](docs/sarif-csv-artifact-plan.md) for the SARIF/CSV output artifact roadmap.
 
 ## Security Model

package/docs/integrations.md

@@ -83,7 +83,21 @@ node src/cli.js check
 - Cursor: writes project `.cursor/mcp.json` using the Cursor `mcpServers` shape. Pass `--config ~/.cursor/mcp.json` for global Cursor setup.
 - `--dry-run` returns the generated config without writing it.
 - `--timeout <ms>` adjusts Codex `startup_timeout_sec` and Gemini `timeout`. It does not change Claude Code startup behavior; set `MCP_TIMEOUT` before launching Claude Code if you need a larger value there.
-- `check` starts the local MCP server and verifies required tools through `initialize` and `tools/list`.
+- `check` starts the local MCP server and verifies required tools, resources, and prompts through MCP discovery methods.
+
+## Client Compatibility Matrix
+
+| Client | Config shape | Scope | Timeout behavior | Restart requirement | Notes |
+| --- | --- | --- | --- | --- | --- |
+| Claude Code | `.mcp.json` `mcpServers` | project | parent `MCP_TIMEOUT`, default 30s | restart Claude Code | no per-server startup timeout field |
+| Codex | TOML `[mcp_servers.artifacty]` | user or explicit config | `startup_timeout_sec = 30.0` | restart Codex session | Windows cold starts may need the 30s default |
+| Gemini CLI | JSON `mcpServers` | user or project | `timeout: 30000` | reload `/mcp` or restart | `trust` is preserved from installer options |
+| GitHub Copilot in VS Code | `.vscode/mcp.json` `servers` | workspace or user profile | client-managed | reload VS Code MCP server | tools are the primary tested surface |
+| Cursor | `.cursor/mcp.json` `mcpServers` | workspace or global | client-managed | restart/reload Cursor MCP | tools are the primary tested surface |
+
+All clients should support MCP tools. Resource and prompt display varies by
+client, so Artifacty's core workflows continue to work through tools even when a
+client does not expose resources or prompts in its UI.
 
 Generate a token for protected HTTP routes:
 
@@ -196,6 +210,25 @@ Then run `/mcp` inside Gemini CLI to confirm that the Artifacty tools are connec
 
 Mutating MCP tools scan content for common API keys and private keys before storage. Pass `allowSecrets: true` only for intentional exceptions.
 
+## MCP Resources and Prompts
+
+Artifacty also exposes read-only MCP resources:
+
+- `artifacty://recent`: recent artifacts with pagination and browser URLs.
+- `artifacty://schema/v1`: Artifact schema v1 Markdown.
+- `artifacty://artifacts/{id}`: artifact JSON with metadata, content, and URLs.
+- `artifacty://artifacts/{id}/raw{?version}`: raw latest or versioned content.
+
+Prompt templates:
+
+- `artifacty_handoff`: continuation handoff.
+- `artifacty_review`: findings-first code review artifact.
+- `artifacty_test_report`: verification evidence.
+- `artifacty_visual_qa`: screenshot/media/browser evidence.
+- `artifacty_release_notes`: release notes with publish evidence and risks.
+
+See [mcp-public-api.md](mcp-public-api.md) for the public MCP surface.
+
 ## Importing Agent Artifacts
 
 Use `artifacty_import` or the CLI `import` command when the artifact was produced by another agent and needs normalization before sharing.

package/docs/mcp-public-api.md

@@ -0,0 +1,68 @@
+# MCP Public API
+
+Artifacty's MCP stdio server is the primary agent-to-agent integration surface.
+The server currently targets MCP protocol `2025-06-18`.
+
+## Capabilities
+
+`initialize` advertises:
+
+- `tools`: Artifact create, import, list, get, update, archive, restore, audit, and info.
+- `resources`: static and dynamic read-only artifact resources.
+- `prompts`: reusable workflow prompt templates.
+
+## Tools
+
+Stable tool names:
+
+- `artifacty_create`: create a native Artifacty artifact.
+- `artifacty_publish`: backwards-compatible alias for `artifacty_create`.
+- `artifacty_import`: convert external Claude, Codex, Gemini, Copilot, Cursor, Artifacty, or generic payloads.
+- `artifacty_list`: list artifacts with `query`, `tag`, `sourceAgent`, `includeArchived`, `limit`, and `offset`.
+- `artifacty_get`: read one artifact by `id` and optional `version`.
+- `artifacty_update`: append an immutable version.
+- `artifacty_archive` / `artifacty_restore`: toggle archive state.
+- `artifacty_audit`: list audit events.
+- `artifacty_info`: return local store and browser URL information.
+
+Tool schemas use Artifacty schema v1 formats and artifact types. New optional
+properties may be added during 0.x releases; existing names should not be
+renamed without a documented migration.
+
+## Resources
+
+Static resources:
+
+- `artifacty://recent`: JSON list of recent artifacts with pagination and browser URLs.
+- `artifacty://schema/v1`: Markdown reference for Artifacty schema v1.
+
+Resource templates:
+
+- `artifacty://artifacts/{id}`: JSON artifact metadata, selected version, content, and URLs.
+- `artifacty://artifacts/{id}/raw{?version}`: raw artifact content for latest or specified version.
+
+Resources are read-only and may record an audit `read` event for artifact content.
+
+## Prompts
+
+Prompt names:
+
+- `artifacty_handoff`
+- `artifacty_review`
+- `artifacty_test_report`
+- `artifacty_visual_qa`
+- `artifacty_release_notes`
+
+Each prompt returns one user message that instructs an agent to create or update
+an Artifacty artifact with discoverable `artifactType`, `sourceAgent`, and tags.
+Prompts accept optional context arguments such as `artifactId`, `goal`, `scope`,
+`target`, or `version`.
+
+## Compatibility Notes
+
+- The MCP server is local stdio only. Remote MCP auth/OAuth is out of scope.
+- Binary media resources return stored base64 text through MCP; browser `/raw`
+  decodes first-class `image` and `video` artifacts into bytes.
+- Clients may display resources and prompts differently. Tools remain the most
+  widely supported integration path across Claude, Codex, Gemini, Copilot, and
+  Cursor.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artifacty",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Local artifact exchange for heterogeneous LLM agents via HTTP and MCP.",
   "type": "module",
   "keywords": [
@@ -37,6 +37,7 @@
     "docs/artifact-schema-v1.md",
     "docs/assets/artifacty.png",
     "docs/integrations.md",
+    "docs/mcp-public-api.md",
     "docs/network-sharing.md",
     "docs/release-checklist.md",
     "docs/sarif-csv-artifact-plan.md",

package/src/cli.js

@@ -4,11 +4,13 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import {
   archiveArtifact,
+  checkStoreIntegrity,
   createArtifact,
   createStore,
   getArtifact,
   listAuditEvents,
-  listArtifacts,
+  listArtifactsPage,
+  rebuildSearchIndex,
   restoreArtifact,
   updateArtifact
 } from "./lib/storage.js";
@@ -200,14 +202,37 @@ async function main() {
   }
 
   if (command === "list") {
-    const artifacts = await listArtifacts(store, {
+    const page = await listArtifactsPage(store, {
       query: options.query,
       tag: Array.isArray(options.tag) ? options.tag[0] : options.tag,
       sourceAgent: options.source,
       includeArchived: options.includeArchived,
-      limit: options.limit
+      limit: options.limit,
+      offset: options.offset
+    });
+    printJson({
+      artifacts: page.artifacts,
+      pagination: paginationJson(page),
+      search: page.search
     });
-    printJson({ artifacts });
+    return;
+  }
+
+  if ((command === "index" || command === "search") && options._[0] === "rebuild") {
+    const result = await rebuildSearchIndex(store);
+    printJson(result);
+    if (!result.fts5) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (command === "integrity" || command === "check-store") {
+    const result = await checkStoreIntegrity(store);
+    printJson(result);
+    if (!result.ok) {
+      process.exitCode = 1;
+    }
     return;
   }
 
@@ -298,7 +323,7 @@ function parseArgs(args) {
 
     if (key === "tag") {
       options.tag = [...(options.tag || []), value];
-    } else if (key === "port" || key === "limit" || key === "version" || key === "schema-version" || key === "timeout" || key === "bytes") {
+    } else if (key === "port" || key === "limit" || key === "offset" || key === "version" || key === "schema-version" || key === "timeout" || key === "bytes") {
       options[toCamelCase(key)] = Number(value);
     } else {
       options[toCamelCase(key)] = value;
@@ -342,6 +367,17 @@ async function withUrls(store, artifact) {
   };
 }
 
+function paginationJson(page) {
+  return {
+    total: page.total,
+    limit: page.limit,
+    offset: page.offset,
+    hasMore: page.hasMore,
+    nextOffset: page.nextOffset,
+    previousOffset: page.previousOffset
+  };
+}
+
 function requireOption(options, name) {
   if (!options[name]) {
     throw new Error(`Missing required option --${name}`);
@@ -370,11 +406,13 @@ Usage:
   artifacty archive <id>
   artifacty restore <id>
   artifacty audit [--artifact <id>] [--limit 100]
+  artifacty index rebuild
+  artifacty integrity
   artifacty export --file <path>
   artifacty backup [--file <path>]
   artifacty import-store --file <path>
   artifacty service plist|install|uninstall [--dry-run] [--plist <path>]
-  artifacty list [--query text] [--tag tag] [--source agent] [--limit 50] [--include-archived]
+  artifacty list [--query text] [--tag tag] [--source agent] [--limit 50] [--offset 0] [--include-archived]
   artifacty show <id> [--version n] [--raw]
 
 Environment:

package/src/lib/check.js

@@ -14,10 +14,25 @@ export const REQUIRED_MCP_TOOLS = [
   "artifacty_info"
 ];
 
+export const REQUIRED_MCP_RESOURCES = [
+  "artifacty://recent",
+  "artifacty://schema/v1"
+];
+
+export const REQUIRED_MCP_PROMPTS = [
+  "artifacty_handoff",
+  "artifacty_review",
+  "artifacty_test_report",
+  "artifacty_visual_qa",
+  "artifacty_release_notes"
+];
+
 export async function checkMcpTools(options = {}) {
   const projectDir = path.resolve(options.projectDir || process.cwd());
   const serverPath = path.resolve(options.serverPath || path.join(projectDir, "src", "mcp-server.js"));
   const requiredTools = options.requiredTools || REQUIRED_MCP_TOOLS;
+  const requiredResources = options.requiredResources || REQUIRED_MCP_RESOURCES;
+  const requiredPrompts = options.requiredPrompts || REQUIRED_MCP_PROMPTS;
   const timeoutMs = Number(options.timeout || 5000);
   const client = spawnMcpClient({
     serverPath,
@@ -39,14 +54,26 @@ export async function checkMcpTools(options = {}) {
     const listed = await client.request("tools/list", {});
     const toolNames = (listed.tools || []).map((tool) => tool.name).sort();
     const missingTools = requiredTools.filter((tool) => !toolNames.includes(tool));
+    const listedResources = await client.request("resources/list", {});
+    const resourceUris = (listedResources.resources || []).map((resource) => resource.uri).sort();
+    const missingResources = requiredResources.filter((resource) => !resourceUris.includes(resource));
+    const listedPrompts = await client.request("prompts/list", {});
+    const promptNames = (listedPrompts.prompts || []).map((prompt) => prompt.name).sort();
+    const missingPrompts = requiredPrompts.filter((prompt) => !promptNames.includes(prompt));
 
     return {
-      ok: missingTools.length === 0,
+      ok: missingTools.length === 0 && missingResources.length === 0 && missingPrompts.length === 0,
       serverPath,
       protocolVersion: initialized.protocolVersion,
       toolCount: toolNames.length,
+      resourceCount: resourceUris.length,
+      promptCount: promptNames.length,
       tools: toolNames,
-      missingTools
+      resources: resourceUris,
+      prompts: promptNames,
+      missingTools,
+      missingResources,
+      missingPrompts
     };
   } finally {
     client.close();

package/src/lib/i18n.js

@@ -15,7 +15,11 @@ const TRANSLATIONS = {
     "language.english": "English",
     "language.korean": "Korean",
     "dashboard.count": "{count} artifacts",
+    "dashboard.range": "{start}-{end} of {total} artifacts",
+    "dashboard.searchBackend": "{backend} search",
     "dashboard.empty": "No artifacts published yet.",
+    "dashboard.previous": "Previous",
+    "dashboard.next": "Next",
     "filter.search": "Search",
     "filter.tag": "Tag",
     "filter.source": "Source",
@@ -69,7 +73,11 @@ const TRANSLATIONS = {
     "language.english": "영어",
     "language.korean": "한국어",
     "dashboard.count": "아티팩트 {count}개",
+    "dashboard.range": "아티팩트 {total}개 중 {start}-{end}",
+    "dashboard.searchBackend": "{backend} 검색",
     "dashboard.empty": "아직 게시된 아티팩트가 없습니다.",
+    "dashboard.previous": "이전",
+    "dashboard.next": "다음",
     "filter.search": "검색",
     "filter.tag": "태그",
     "filter.source": "소스",

package/src/lib/render.js

@@ -2,17 +2,26 @@ import { EDITOR_CLIENT_PATH, VIEWER_CLIENT_PATH, editorImportMapJson } from "./e
 import { createI18n, DEFAULT_LOCALE, editorMessages, localizedHref, switchLocaleHref } from "./i18n.js";
 import { ARTIFACT_FORMATS, ARTIFACT_TYPES } from "./storage.js";
 
-export function renderDashboard({ artifacts, baseUrl, filters = {}, locale = DEFAULT_LOCALE, currentPath = "/" }) {
+export function renderDashboard({ artifacts, baseUrl, filters = {}, pagination, locale = DEFAULT_LOCALE, currentPath = "/" }) {
   const view = viewContext(locale, currentPath);
+  const total = pagination?.total ?? artifacts.length;
+  const start = artifacts.length ? (pagination?.offset ?? 0) + 1 : 0;
+  const end = artifacts.length ? (pagination?.offset ?? 0) + artifacts.length : 0;
+  const searchBackend = pagination?.search?.backend;
+  const pager = renderDashboardPager({ pagination, filters, view });
   const rows = artifacts
     .map((artifact) => {
       const tags = artifact.tags.map((tag) => `<span class="tag">${escapeHtml(tag)}</span>`).join("");
       const status = artifact.archivedAt ? statusBadge("archived") : "";
+      const snippet = artifact.searchSnippet
+        ? `<span class="row-snippet">${escapeHtml(artifact.searchSnippet)}</span>`
+        : "";
       return `
         <a class="artifact-row" href="${view.href(`/artifacts/${encodeURIComponent(artifact.id)}`)}">
           <span class="row-main">
             <strong>${escapeHtml(artifact.title)}</strong>
             <span>${escapeHtml(artifact.id)}</span>
+            ${snippet}
           </span>
           <span>${escapeHtml(artifact.sourceAgent)}</span>
           ${typeBadge(artifact.artifactType || "document")}
@@ -44,10 +53,12 @@ export function renderDashboard({ artifacts, baseUrl, filters = {}, locale = DEF
       </header>
       <main class="dashboard">
         <section class="toolbar">
-          <span>${view.text("dashboard.count", { count: artifacts.length })}</span>
+          <span>${view.text("dashboard.range", { start, end, total })}</span>
+          ${searchBackend ? `<span>${view.text("dashboard.searchBackend", { backend: searchBackend })}</span>` : ""}
         </section>
         <form class="filter-form" method="get" action="/">
           ${localeInput(view.locale)}
+          ${filters.limit ? `<input type="hidden" name="limit" value="${escapeAttribute(filters.limit)}">` : ""}
           <input name="q" value="${escapeAttribute(filters.query || "")}" placeholder="${view.attr("filter.search")}">
           <input name="tag" value="${escapeAttribute(filters.tag || "")}" placeholder="${view.attr("filter.tag")}">
           <input name="sourceAgent" value="${escapeAttribute(filters.sourceAgent || "")}" placeholder="${view.attr("filter.source")}">
@@ -58,12 +69,52 @@ export function renderDashboard({ artifacts, baseUrl, filters = {}, locale = DEF
         <section class="artifact-list">
           ${rows || `<div class="empty">${view.text("dashboard.empty")}</div>`}
         </section>
+        ${pager}
       </main>
     `,
     locale: view.locale
   });
 }
 
+function renderDashboardPager({ pagination, filters, view }) {
+  if (!pagination || pagination.total <= pagination.limit) {
+    return "";
+  }
+
+  const previous = pagination.previousOffset === null
+    ? `<span class="pager-disabled">${view.text("dashboard.previous")}</span>`
+    : `<a href="${view.href(dashboardPageHref(filters, pagination.previousOffset))}">${view.text("dashboard.previous")}</a>`;
+  const next = pagination.nextOffset === null
+    ? `<span class="pager-disabled">${view.text("dashboard.next")}</span>`
+    : `<a href="${view.href(dashboardPageHref(filters, pagination.nextOffset))}">${view.text("dashboard.next")}</a>`;
+
+  return `<nav class="pager" aria-label="Pagination">${previous}${next}</nav>`;
+}
+
+function dashboardPageHref(filters, offset) {
+  const params = new URLSearchParams();
+  if (filters.query) {
+    params.set("q", filters.query);
+  }
+  if (filters.tag) {
+    params.set("tag", filters.tag);
+  }
+  if (filters.sourceAgent) {
+    params.set("sourceAgent", filters.sourceAgent);
+  }
+  if (filters.includeArchived) {
+    params.set("includeArchived", "true");
+  }
+  if (filters.limit) {
+    params.set("limit", filters.limit);
+  }
+  if (offset > 0) {
+    params.set("offset", String(offset));
+  }
+  const query = params.toString();
+  return query ? `/?${query}` : "/";
+}
+
 export function renderArtifactFormPage({ mode, baseUrl, artifact, version, content, authToken = "", locale = DEFAULT_LOCALE, currentPath = "/" }) {
   const view = viewContext(locale, currentPath);
   const isEdit = mode === "edit";
@@ -705,6 +756,34 @@ export function pageShell({ title, body, head = "", afterBody = "", locale = DEF
       background: var(--panel);
       box-shadow: 0 1px 2px rgba(15, 23, 42, 0.04);
     }
+    .pager {
+      display: flex;
+      justify-content: flex-end;
+      gap: 8px;
+      margin-top: 14px;
+      font-family: var(--mono);
+      font-size: 12.5px;
+    }
+    .pager a,
+    .pager-disabled {
+      display: inline-flex;
+      min-height: 34px;
+      align-items: center;
+      justify-content: center;
+      padding: 5px 12px;
+      border: 1px solid var(--line-2);
+      border-radius: 8px;
+      background: var(--panel);
+      color: var(--muted);
+    }
+    .pager a:hover {
+      border-color: var(--accent);
+      color: var(--text);
+      text-decoration: none;
+    }
+    .pager-disabled {
+      opacity: 0.55;
+    }
     .editor-form {
       display: grid;
       gap: 16px;
@@ -889,6 +968,13 @@ export function pageShell({ title, body, head = "", afterBody = "", locale = DEF
       font-size: 12px;
       color: var(--faint);
     }
+    .row-main .row-snippet {
+      color: var(--muted);
+      white-space: normal;
+      overflow: visible;
+      text-overflow: clip;
+      overflow-wrap: anywhere;
+    }
     .artifact-row > span:not(.row-main):not(.tags):not(.badge) {
       font-family: var(--mono);
       font-size: 12.5px;