artifacty 0.7.0 → 0.9.0

package/README.md

@@ -82,6 +82,23 @@ artifacty install all
 artifacty check
 ```
 
+For a central internal server, enable the HTTP MCP endpoint on the server and
+let users issue personal MCP/API tokens from the account page:
+
+```bash
+ARTIFACTY_BOOTSTRAP_TOKEN="$(artifacty token --raw)"
+artifacty serve --host 10.0.0.50 --share-mode team --api-token "$ARTIFACTY_BOOTSTRAP_TOKEN" --mcp-http --foreground
+# Open http://10.0.0.50:8787/login, create the first admin, then create a personal token at /account.
+artifacty install all --mcp-url http://10.0.0.50:8787/mcp --api-token "$ARTIFACTY_PERSONAL_TOKEN"
+```
+
+Run diagnostics for the local runtime, store, server, service definitions, and MCP discovery:
+
+```bash
+artifacty doctor
+artifacty doctor --skip-mcp
+```
+
 Use `artifacty install codex --timeout 30000` or
 `artifacty install gemini --timeout 30000` to tune supported MCP client timeouts.
 
@@ -178,6 +195,7 @@ Run the MCP server:
 
 ```bash
 artifacty-mcp
+ARTIFACTY_MCP_MODE=bridge ARTIFACTY_MCP_URL=http://10.0.0.50:8787/mcp ARTIFACTY_API_TOKEN=... artifacty-mcp
 ```
 
 MCP clients can create artifacts with `artifacty_create`. `artifacty_publish` remains as a backwards-compatible alias.
@@ -190,6 +208,7 @@ Operational commands:
 
 ```bash
 artifacty audit --limit 20
+artifacty doctor
 artifacty index rebuild
 artifacty integrity
 artifacty backup
@@ -288,12 +307,14 @@ Schema and storage:
 - 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/central-team-deployment-design.md](docs/central-team-deployment-design.md) for central team deployment.
 - See [docs/sarif-csv-artifact-plan.md](docs/sarif-csv-artifact-plan.md) for the SARIF/CSV output artifact roadmap.
 
 ## Security Model
 
 - The HTTP server binds to `127.0.0.1` by default.
 - If `ARTIFACTY_API_TOKEN` is set, HTTP API routes require `Authorization: Bearer <token>` or `x-artifacty-token`; scripts should prefer headers over `?token=...` URLs.
+- When users exist, personal API tokens issued from `/account` also authenticate HTTP API and MCP requests, and audit logs record the token owner's email as `actor`.
 - API token checks use timing-safe digest comparison.
 - Binding outside localhost requires both `ARTIFACTY_SHARE_MODE=lan` or `team` and `ARTIFACTY_API_TOKEN`.
 - Non-local sharing is intended for trusted LAN or VPN sessions. Prefer a specific interface IP over `0.0.0.0`, keep React rendering disabled, and see [docs/network-sharing.md](docs/network-sharing.md).

package/docs/central-team-deployment-design.md

@@ -0,0 +1,208 @@
+# Central Team Deployment Design
+
+This document defines the design for running Artifacty as a shared internal
+service, where many users connect Claude Code, Codex, Gemini, GitHub Copilot,
+Cursor, or another MCP client to one central Artifacty server.
+
+## Problem
+
+Artifacty is local-first by default. The HTTP server can listen on a LAN
+address, and the MCP server can either read and write the local `ARTIFACTY_HOME`
+store directly or run as a stdio bridge to a central `/mcp` endpoint. The
+installer `--url` option only controls the browser URL returned in MCP
+responses; central MCP mode is selected with `--mcp-url`.
+
+For a central deployment, every MCP client must write through the central
+service instead of touching local SQLite or shared network files. The preferred
+central surface is the native HTTP `/mcp` endpoint. A local stdio bridge remains
+the default installer path for broad client compatibility.
+
+## Goals
+
+- One central Artifacty store per internal deployment.
+- Native central MCP over Streamable HTTP for clients that support remote MCP.
+- Per-user local stdio bridge compatibility for clients that only support local
+  stdio MCP configuration.
+- Stable install commands that can target a central server.
+- Token-authenticated HTTP writes with no token leakage through query strings.
+- Clear audit attribution for user, agent, host, and client surface.
+- Safe defaults for LAN/team operation without weakening local-first behavior.
+
+## Non-Goals
+
+- Public internet hosting without a reverse proxy, TLS, and stronger auth.
+- SQLite access over NFS or SMB as the recommended sharing model.
+- Relaxing browser-origin checks to make remote browser writes easier.
+- Removing the local stdio MCP path for single-user or legacy clients.
+
+## Target Architecture
+
+```text
+MCP client with remote transport support
+  -> https://artifacty.internal/mcp
+  -> central Artifacty MCP handler
+  -> central SQLite store and immutable version files
+  -> browser dashboard at the same central URL
+
+MCP client with stdio-only support
+  -> local Artifacty stdio bridge
+  -> https://artifacty.internal/mcp
+  -> same central MCP handler
+```
+
+The central MCP handler is the canonical team integration surface. HTTP JSON API
+routes remain useful for scripts, browser workflows, and compatibility, but MCP
+tool semantics should not be reimplemented separately in a REST-only bridge.
+Both stdio and Streamable HTTP should share the same tool/resource/prompt
+dispatcher.
+
+## Runtime Modes
+
+Artifacty supports these explicit MCP operation modes:
+
+- `local`: default mode; MCP reads and writes the local store directly.
+- `streamable-http`: a central `/mcp` endpoint serves MCP over HTTP when
+  `--mcp-http` or `ARTIFACTY_MCP_HTTP=true` is enabled.
+- `bridge`: local stdio process forwards MCP JSON-RPC to a remote `/mcp`
+  endpoint for clients that cannot connect to remote MCP directly.
+
+Mode selection should be explicit. `ARTIFACTY_URL` must remain the public
+browser URL override for backwards compatibility. New variables should define
+remote MCP behavior:
+
+```bash
+ARTIFACTY_MCP_MODE=bridge
+ARTIFACTY_MCP_URL=https://artifacty.internal/mcp
+ARTIFACTY_API_TOKEN=...
+```
+
+`ARTIFACTY_URL` may default to the central browser URL when not set, but browser
+links and MCP transport URLs should stay separate in the code and documentation.
+
+## Installer UX
+
+The installer exposes central-server options for every supported client:
+
+```bash
+artifacty install codex \
+  --mcp-url https://artifacty.internal/mcp \
+  --api-token "$ARTIFACTY_API_TOKEN"
+```
+
+Equivalent commands work for `claude`, `gemini`, `copilot`, `cursor`, and `all`.
+
+The current installer generates a local bridge entry for every supported client:
+
+```json
+{
+  "ARTIFACTY_MCP_MODE": "bridge",
+  "ARTIFACTY_MCP_URL": "https://artifacty.internal/mcp",
+  "ARTIFACTY_API_TOKEN": "..."
+}
+```
+
+The installer should continue to support `--url` for link-only overrides.
+`--mcp-url` should imply central MCP behavior; `--url` should not.
+
+## Central Server Operation
+
+A minimal LAN deployment should bind to a specific internal interface and require
+token auth:
+
+```bash
+ARTIFACTY_API_TOKEN="$(artifacty token --raw)"
+ARTIFACTY_SHARE_MODE=team \
+artifacty serve \
+  --host 10.0.0.50 \
+  --port 8787 \
+  --api-token "$ARTIFACTY_API_TOKEN" \
+  --mcp-http
+```
+
+Open `/login` after the server starts. If no users exist, the first successful
+login form creates an administrator. Administrators can create users from
+`/admin/users`, and every user can create or revoke personal API tokens from
+`/account`. Use those personal tokens for `artifacty install ... --api-token`
+so MCP and API audit logs record the user's email as `actor`.
+
+Production-like internal deployments should run Artifacty behind a TLS reverse
+proxy, keep `ARTIFACTY_ENABLE_REACT_RENDERER` disabled unless the team trusts
+all artifact authors, and store `ARTIFACTY_HOME` on local server disk with
+regular backups.
+
+The central server exposes `/mcp` only when explicitly enabled. This keeps the
+local browser/API server behavior unchanged while making team MCP exposure an
+intentional operating mode.
+
+## MCP Requirements
+
+Remote MCP mode needs complete parity with local MCP tools:
+
+- create/import/list/get/update/archive/restore/audit/info
+- resources: recent artifact list, artifact by ID, schema
+- prompts: handoff, review, test report, visual QA, release notes
+
+The stdio server and `/mcp` HTTP endpoint call the same dispatcher so tool
+schemas, resources, prompts, validation, and audit behavior cannot drift.
+
+All remote MCP requests must send `Authorization: Bearer` or an equivalent
+header accepted by the central endpoint. Remote MCP should never place tokens in
+URLs.
+
+## Audit and Identity
+
+Remote MCP requests should include headers such as:
+
+```text
+x-artifacty-client: codex
+x-artifacty-actor: user@example.com
+x-artifacty-host: IRAE-MACBOOK
+```
+
+The server records the authenticated user's email as the audit `actor` when a
+personal token is used. The `x-artifacty-actor` header remains a compatibility
+fallback for the bootstrap/global token path.
+
+## Security Model
+
+Central mode increases the trust boundary from one machine to a team network.
+Required safeguards:
+
+- non-loopback binding still requires `ARTIFACTY_SHARE_MODE=lan|team`
+- central API always requires `ARTIFACTY_API_TOKEN`
+- remote MCP uses header auth only
+- shared instances should prefer TLS through a reverse proxy
+- browser-origin protections remain in place
+- artifact renderers continue treating stored content as untrusted
+
+For larger organizations, the next step after personal tokens is scoped tokens,
+token rotation policy, and SSO/OIDC.
+
+## Current Implementation
+
+- `artifacty serve --mcp-http` exposes `POST /mcp`.
+- `ARTIFACTY_MCP_MODE=bridge` forwards stdio JSON-RPC to `ARTIFACTY_MCP_URL`.
+- `artifacty install <agent> --mcp-url ... --api-token ...` writes bridge env
+  config for Claude, Codex, Gemini, GitHub Copilot, and Cursor.
+- `/login`, `/account`, and `/admin/users` provide server-side user management,
+  administrator/user roles, and personal token issue/revoke flows.
+- Remote MCP requests use header auth and never put tokens in URLs.
+- Tests cover direct HTTP MCP calls and stdio bridge calls to a token-protected
+  central server.
+
+## Remaining Work
+
+- Client-specific direct remote MCP config generation where the client supports
+  it.
+- Scoped tokens, token rotation policy, and stronger audit identity.
+- Optional reverse proxy examples for TLS termination.
+
+## Acceptance Criteria
+
+- A user can install Artifacty MCP against a central `/mcp` endpoint without
+  sharing a filesystem.
+- Artifacts created from any supported MCP client appear in the central
+  dashboard and are visible to other clients.
+- Local MCP behavior remains unchanged when remote mode is not configured.
+- Tokens are sent only in headers.
+- CI covers remote MCP parity against the HTTP API.

package/docs/integrations.md

@@ -37,6 +37,15 @@ The lifecycle commands are intended to be cross-platform:
 - Windows: `start` hides the child console window, and `stop` uses `taskkill /PID <pid> /T`, falling back to `/F` when Windows requires forceful termination. `--force` uses `/F` immediately.
 - All platforms: `status` combines the managed pid file with the HTTP `/health` endpoint, so a stale pid alone is not reported as healthy.
 
+Run diagnostics when setup behaves unexpectedly:
+
+```bash
+node src/cli.js doctor
+node src/cli.js doctor --skip-mcp
+```
+
+`doctor` checks Node version support, local exposure settings, store integrity, managed server health, service definition rendering, and MCP discovery. A stopped server is reported as a warning, not a failure.
+
 For login/startup persistence, use the operating system's service manager. Artifacty's `service` command can generate macOS LaunchAgent, Linux systemd user-unit, and Windows Task Scheduler definitions.
 
 Create artifacts directly in the browser at `http://127.0.0.1:8787/new`.
@@ -59,6 +68,8 @@ Useful environment variables:
 
 - `ARTIFACTY_HOME`: store directory, shared by all agents.
 - `ARTIFACTY_URL`: optional browser URL override. Leave it unset to let MCP read the last running server URL from `server.json`.
+- `ARTIFACTY_MCP_MODE`: `local` by default, or `bridge` to forward stdio MCP to a central HTTP MCP endpoint.
+- `ARTIFACTY_MCP_URL`: central MCP endpoint used by bridge mode, for example `http://10.0.0.50:8787/mcp`.
 - `ARTIFACTY_API_TOKEN`: required token for HTTP API routes when configured. Generate one with `node src/cli.js token --raw`.
 - `ARTIFACTY_SHARE_MODE`: set to `lan` or `team` before binding outside localhost.
 - `ARTIFACTY_ALLOW_SECRETS`: set to `true` only when intentionally storing detected secrets.
@@ -77,14 +88,33 @@ node src/cli.js install all
 node src/cli.js check
 ```
 
+Central team server setup:
+
+```bash
+ARTIFACTY_BOOTSTRAP_TOKEN="$(node src/cli.js token --raw)"
+node src/cli.js serve --foreground \
+  --host 10.0.0.50 \
+  --share-mode team \
+  --api-token "$ARTIFACTY_BOOTSTRAP_TOKEN" \
+  --mcp-http
+# Open http://10.0.0.50:8787/login, create the first admin, then create a personal token at /account.
+node src/cli.js install all \
+  --mcp-url http://10.0.0.50:8787/mcp \
+  --api-token "$ARTIFACTY_PERSONAL_TOKEN"
+```
+
 - Claude: writes project `.mcp.json`. Claude Code's startup timeout is controlled by the parent `MCP_TIMEOUT` environment variable and defaults to 30 seconds, so Artifacty does not add a per-server `.mcp.json` `timeout` field.
 - Codex: writes or replaces the `[mcp_servers.artifacty]` block in `~/.codex/config.toml` unless `--config` is provided. The generated block uses a 30 second startup timeout so slower Windows or cold-start environments can load the MCP server reliably.
 - Gemini: writes project `.gemini/settings.json` with a 30 second timeout.
 - GitHub Copilot in VS Code: writes workspace `.vscode/mcp.json` using the VS Code `servers` shape. Pass `--config` to target a user-profile `mcp.json` instead.
 - 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.
+- `--mcp-url <url>` installs stdio bridge mode for central Artifacty. If the URL has no path, `/mcp` is appended.
+- `--api-token <token>` is written into the generated MCP environment for bridge mode. For central servers, prefer a personal token issued from `/account`.
+- `--url <url>` remains a browser-link override and does not enable central MCP by itself.
 - `--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, resources, and prompts through MCP discovery methods.
+- `doctor` combines MCP discovery with runtime, storage, server, and service diagnostics.
 
 ## Client Compatibility Matrix
 
@@ -268,6 +298,7 @@ tests.
 - `GET /import`: browser artifact import form.
 - `POST /import`: convert and save pasted agent output.
 - `GET /health`: health check.
+- `POST /mcp`: token-protected MCP Streamable HTTP JSON-RPC endpoint when `--mcp-http` or `ARTIFACTY_MCP_HTTP=true` is enabled.
 - `GET /api/artifacts`: list artifacts.
 - `POST /api/artifacts`: create artifact.
 - `POST /api/import`: convert and save an agent-produced artifact.
@@ -285,7 +316,7 @@ tests.
 - `GET /artifacts/:id/diff`: compare two versions.
 - `GET /artifacts/:id/raw?version=n`: raw content.
 
-When `ARTIFACTY_API_TOKEN` is configured, `/api/*` routes require either `Authorization: Bearer <token>` or `x-artifacty-token: <token>`. Browser forms can also carry `?token=<token>` in the URL, which is copied to hidden form fields for local team workflows.
+When `ARTIFACTY_API_TOKEN` is configured, `/api/*` routes require either `Authorization: Bearer <token>` or `x-artifacty-token: <token>`. When users exist, personal tokens issued from `/account` also authenticate API and MCP requests and are mapped to the token owner's email in audit logs. Browser forms can also carry `?token=<token>` in the URL, which is copied to hidden form fields for local team workflows.
 
 Renderer notes:
 

package/docs/mcp-public-api.md

@@ -1,7 +1,10 @@
 # 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`.
+Artifacty's MCP server is the primary agent-to-agent integration surface. It
+supports local stdio MCP by default, a token-protected HTTP `/mcp` endpoint when
+enabled on the browser server, and stdio bridge mode for clients that need local
+stdio config but should write to a central Artifacty server. The server
+currently targets MCP protocol `2025-06-18`.
 
 ## Capabilities
 
@@ -23,7 +26,7 @@ Stable tool names:
 - `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.
+- `artifacty_info`: return store, browser URL, transport, and protocol 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
@@ -60,7 +63,13 @@ Prompts accept optional context arguments such as `artifactId`, `goal`, `scope`,
 
 ## Compatibility Notes
 
-- The MCP server is local stdio only. Remote MCP auth/OAuth is out of scope.
+- Local stdio remains the default. Enable the central HTTP endpoint with
+  `artifacty serve --mcp-http` and install bridge mode with
+  `artifacty install <agent> --mcp-url http://host:8787/mcp --api-token <token>`.
+- On central servers, use a personal token from `/account` so audit logs record
+  the token owner's email as the artifact actor.
+- Remote MCP currently uses bearer/header token auth. OAuth and per-user scoped
+  tokens are future hardening work.
 - 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

package/docs/network-sharing.md

@@ -16,6 +16,16 @@ If another device on a trusted LAN or private VPN needs read access, prefer bind
 artifacty serve --host 192.168.1.20 --share-mode lan --generate-token
 ```
 
+For a central internal MCP server, enable `/mcp` explicitly and install clients
+with `--mcp-url` and a personal token from `/account`:
+
+```bash
+ARTIFACTY_BOOTSTRAP_TOKEN="$(artifacty token --raw)"
+artifacty serve --host 10.0.0.50 --share-mode team --api-token "$ARTIFACTY_BOOTSTRAP_TOKEN" --mcp-http --foreground
+# Open /login to create the first admin, then /account to issue a personal token.
+artifacty install all --mcp-url http://10.0.0.50:8787/mcp --api-token "$ARTIFACTY_PERSONAL_TOKEN"
+```
+
 Use `0.0.0.0` only when you intentionally want Artifacty to listen on every network interface:
 
 ```bash
@@ -43,3 +53,6 @@ Do not relax the origin check just to make remote browser writes easier. A futur
 Artifact content is untrusted. HTML, SVG, Mermaid, and React artifacts are rendered with sandboxing and CSP controls, but shared viewing still means content reaches another user's browser. Keep `ARTIFACTY_ENABLE_REACT_RENDERER` disabled for LAN sessions unless every viewer trusts the artifact source.
 
 See [threat-model.md](threat-model.md) for the full trust-boundary summary.
+
+For a durable internal deployment where many MCP clients share one central
+Artifacty instance, see [central-team-deployment-design.md](central-team-deployment-design.md).

package/docs/release-checklist.md

@@ -10,6 +10,12 @@ npm run release:check
 
 This runs syntax checks, the full Node test suite, and a local smoke test that starts the HTTP server with token auth enabled, creates an artifact, verifies secret blocking, reads audit logs, writes a backup, and checks MCP tool/resource/prompt discovery.
 
+Run the local diagnostics pass:
+
+```bash
+artifacty doctor
+```
+
 ## Packaging
 
 - Confirm `package.json` `version` and `files` are intentional.
@@ -47,4 +53,5 @@ This runs syntax checks, the full Node test suite, and a local smoke test that s
 
 - Export a backup before upgrades: `artifacty backup`.
 - Confirm `artifacty audit --limit 20` shows recent create/update/read/archive events.
+- Confirm `artifacty doctor` reports no failures. A stopped server warning is acceptable when intentionally checking an offline store.
 - For background service installs, dry-run first: `artifacty service install --dry-run`. Use `--platform macos|linux|windows` to review another OS definition.

package/docs/threat-model.md

@@ -8,6 +8,7 @@ operator, one local store, and trusted local MCP clients by default.
 - Artifact content, including generated code, reports, screenshots, and media.
 - Artifact metadata, tags, audit records, and version history.
 - API tokens and generated startup tokens.
+- User accounts, password hashes, browser sessions, and personal API tokens.
 - Local MCP client configuration files.
 - The Artifacty SQLite database and immutable version files.
 
@@ -16,7 +17,11 @@ operator, one local store, and trusted local MCP clients by default.
 - **HTTP browser server**: local by default, optionally reachable on LAN/team
   networks when explicitly configured.
 - **MCP stdio server**: local process launched by an MCP client. It inherits the
-  local user account's filesystem permissions.
+  local user account's filesystem permissions. In bridge mode, it forwards
+  JSON-RPC to a configured central `/mcp` endpoint instead of touching local
+  storage.
+- **HTTP MCP endpoint**: optional `POST /mcp` endpoint exposed only when
+  `--mcp-http` or `ARTIFACTY_MCP_HTTP=true` is configured.
 - **Artifact renderers**: untrusted content is rendered inside browser sandbox
   boundaries where practical.
 - **Storage**: Artifacty stores content under `ARTIFACTY_HOME`; anyone with
@@ -50,6 +55,8 @@ Controls:
 - Scripts should use `x-artifacty-token` or `Authorization: Bearer <token>`.
 - Browser form token URLs exist only for local convenience.
 - Token comparisons use timing-safe digest comparison.
+- Personal API tokens are stored only as hashes.
+- Browser sessions use `HttpOnly` and `SameSite=Lax` cookies.
 
 Guidance: rotate tokens after sharing sessions, prefer header-based tokens for
 scripts, and use generated startup tokens only for temporary interactive shares.
@@ -98,22 +105,29 @@ of sensitive data.
 
 ### MCP Tool Abuse
 
-Risk: an MCP client can create, update, import, archive, restore, and read local
-artifacts through stdio.
+Risk: an MCP client can create, update, import, archive, restore, and read
+artifacts through local stdio or the central HTTP MCP endpoint.
 
 Controls:
 
-- MCP is local stdio only.
+- Local stdio remains the default.
+- The HTTP MCP endpoint is disabled unless explicitly enabled.
+- Remote MCP requests require the configured API token.
+- Stdio bridge mode sends tokens in headers, not URLs.
+- Personal tokens map requests to a server-side user record for audit actor
+  attribution.
 - MCP writes go through the same secret scan and audit paths as CLI/HTTP writes.
 - MCP resources are read-only.
 
-Guidance: install Artifacty MCP only in clients and workspaces you trust.
+Guidance: install Artifacty MCP only in clients and workspaces you trust. For
+central deployments, prefer TLS through a reverse proxy and rotate shared tokens
+after team changes.
 
 ## Out of Scope
 
 - Public internet hosting without a separate TLS/auth proxy.
 - Multi-user browser write access.
-- OAuth or remote MCP authorization.
+- OAuth, scoped tokens, or per-user remote MCP authorization.
 - Per-artifact ACLs.
 - Encrypted-at-rest storage.
 - Malware analysis of arbitrary artifact content.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artifacty",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Local artifact exchange for heterogeneous LLM agents via HTTP and MCP.",
   "type": "module",
   "keywords": [
@@ -36,6 +36,7 @@
     "src",
     "docs/artifact-schema-v1.md",
     "docs/assets/artifacty.png",
+    "docs/central-team-deployment-design.md",
     "docs/integrations.md",
     "docs/mcp-public-api.md",
     "docs/network-sharing.md",

package/src/cli.js

@@ -22,6 +22,7 @@ import { serviceCommand } from "./lib/service.js";
 import { backgroundStatus, startBackgroundServer, stopBackgroundServer } from "./lib/background.js";
 import { resolvePublicBaseUrl } from "./lib/server-state.js";
 import { generateToken } from "./lib/token.js";
+import { runDoctor } from "./lib/doctor.js";
 import { startServer } from "./server.js";
 
 const PACKAGE_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
@@ -67,7 +68,8 @@ async function main() {
       home: options.home,
       apiToken: generatedToken?.token || options.apiToken,
       shareMode: options.shareMode,
-      allowSecrets: options.allowSecrets
+      allowSecrets: options.allowSecrets,
+      mcpHttp: options.mcpHttp
     });
     process.stderr.write(`Artifacty listening on ${server.url}\n`);
     process.stderr.write(`Store: ${server.store.home}\n`);
@@ -105,6 +107,27 @@ async function main() {
     return;
   }
 
+  if (command === "doctor") {
+    const result = await runDoctor({
+      packageRoot: PACKAGE_ROOT,
+      serverPath: options.serverPath,
+      url: options.url,
+      home: options.home,
+      host: options.host,
+      port: options.port,
+      apiToken: options.apiToken,
+      shareMode: options.shareMode,
+      allowSecrets: options.allowSecrets,
+      timeout: options.timeout,
+      skipMcp: options.skipMcp
+    });
+    printJson(result);
+    if (!result.ok) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
   if (command === "publish") {
     const content = await readContent(options);
     const artifact = await createArtifact(store, {
@@ -161,6 +184,9 @@ async function main() {
       configPath: options.config,
       serverPath: options.serverPath,
       url: options.url,
+      mcpUrl: options.mcpUrl,
+      apiToken: options.apiToken,
+      transport: options.transport,
       home: options.home,
       dryRun: options.dryRun,
       trust: options.trust,
@@ -287,6 +313,7 @@ async function main() {
       apiToken: options.apiToken,
       shareMode: options.shareMode,
       allowSecrets: options.allowSecrets,
+      mcpHttp: options.mcpHttp,
       host: options.host,
       port: options.port,
       home: options.home,
@@ -324,7 +351,7 @@ function parseArgs(args) {
     }
 
     const key = arg.slice(2);
-    if (key === "raw" || key === "dry-run" || key === "trust" || key === "include-archived" || key === "allow-secrets" || key === "generate-token" || key === "detach" || key === "foreground" || key === "force") {
+    if (key === "raw" || key === "dry-run" || key === "trust" || key === "include-archived" || key === "allow-secrets" || key === "generate-token" || key === "detach" || key === "foreground" || key === "force" || key === "skip-mcp" || key === "mcp-http") {
       options[toCamelCase(key)] = true;
       continue;
     }
@@ -407,14 +434,15 @@ function printHelp() {
 
 Usage:
   artifacty token [--bytes 32] [--raw]
-  artifacty serve [--host 127.0.0.1] [--port 8787] [--home ~/.artifacty] [--api-token token] [--generate-token] [--bytes 32] [--foreground]
+  artifacty serve [--host 127.0.0.1] [--port 8787] [--home ~/.artifacty] [--api-token token] [--generate-token] [--bytes 32] [--mcp-http] [--foreground]
   artifacty serve --foreground [--generate-token]
-  artifacty start [--host 127.0.0.1] [--port 8787] [--home ~/.artifacty] [--api-token token] [--generate-token] [--timeout 30000]
+  artifacty start [--host 127.0.0.1] [--port 8787] [--home ~/.artifacty] [--api-token token] [--generate-token] [--mcp-http] [--timeout 30000]
   artifacty status [--home ~/.artifacty]
   artifacty stop [--home ~/.artifacty] [--timeout 30000] [--force]
+  artifacty doctor [--home ~/.artifacty] [--skip-mcp] [--timeout 5000]
   artifacty publish --title <title> (--file <path> | --content <text>) [--format html|markdown|text|json|code|svg|mermaid|react] [--source agent] [--tag tag]
   artifacty import --agent claude|codex|gemini|copilot|cursor|auto (--file <path> | --content <text>) [--title <title>] [--format html|markdown|text|json|code|svg|mermaid|react] [--tag tag]
-  artifacty install claude|codex|gemini|copilot|cursor|all [--dry-run] [--config <path>] [--server-path <path>] [--url http://127.0.0.1:8787] [--timeout 30000]
+  artifacty install claude|codex|gemini|copilot|cursor|all [--dry-run] [--config <path>] [--server-path <path>] [--url http://127.0.0.1:8787] [--mcp-url http://127.0.0.1:8787/mcp] [--api-token token] [--transport local|bridge] [--timeout 30000]
   artifacty check [--server-path <path>] [--timeout 5000]
   artifacty update <id> (--file <path> | --content <text>) [--title <title>] [--format html|markdown|text|json|code|svg|mermaid|react]
   artifacty archive <id>
@@ -425,13 +453,15 @@ Usage:
   artifacty export --file <path>
   artifacty backup [--file <path>]
   artifacty import-store --file <path>
-  artifacty service plist|unit|task|install|uninstall [--platform macos|linux|windows] [--dry-run] [--path <path>]
+  artifacty service plist|unit|task|install|uninstall [--platform macos|linux|windows] [--dry-run] [--path <path>] [--mcp-http]
   artifacty list [--query text] [--tag tag] [--source agent] [--limit 50] [--offset 0] [--include-archived]
   artifacty show <id> [--version n] [--raw]
 
 Environment:
   ARTIFACTY_HOME           Storage directory. Defaults to ~/.artifacty
   ARTIFACTY_URL            Public URL override. Otherwise CLI/MCP read the last running server URL
+  ARTIFACTY_MCP_URL        Central MCP HTTP endpoint used by bridge mode
+  ARTIFACTY_MCP_MODE       local or bridge. bridge forwards stdio MCP to ARTIFACTY_MCP_URL
   ARTIFACTY_API_TOKEN      Required token for HTTP API and LAN mode
   ARTIFACTY_SHARE_MODE     Use lan or team before binding outside localhost
   ARTIFACTY_ALLOW_SECRETS  Set true only to intentionally store detected secrets
@@ -462,6 +492,7 @@ function serverOptions(options) {
     allowSecrets: options.allowSecrets,
     generateToken: options.generateToken,
     bytes: options.bytes,
+    mcpHttp: options.mcpHttp,
     timeout: options.timeout
   };
 }

package/src/lib/background.js

@@ -235,6 +235,9 @@ export function buildServerArgs(options, store) {
   if (options.allowSecrets) {
     args.push("--allow-secrets");
   }
+  if (options.mcpHttp) {
+    args.push("--mcp-http");
+  }
   return args;
 }