artifacta

Artifacta MCP 服务

Artifacta 的官方 MCP 服务——专为 AI Agent 打造的制品存储库。Agent 可保存运行输出（文件、报告、数据集、构建结果）及会话和 Agent 元数据，在不同会话间交接，并通过限时下载链接分享。基于内容哈希去重，因此重复存储相同字节无需付费。

已列入官方 MCP 注册表，名称为 io.artifacta/mcp。

两种实现具有相同的工具接口、错误约定和路径约束引擎：

目录	包	运行环境
typescript/	@artifacta-mcp/mcp	Node 20+
python/	artifacta-mcp	Python 3.10+

安装为 Claude Code 插件

对于 Claude Code，最快的方式是使用本仓库兼作的插件市场——它会配置托管服务，并且提供一个自动保存运行输出的技能：

/plugin marketplace add SagaPeak/artifacta-mcp
/plugin install artifacta@artifacta

这会将下方快速开始中相同的托管 MCP 连接与 persisting-outputs 技能打包在一起（/artifacta:persisting-outputs；也会在会话中有值得保存的输出时自动触发）。使用 /plugin marketplace update artifacta 更新插件。请参阅插件设置指南。

快速开始

最快的连接方式是使用托管服务——无需安装，也无需 API 密钥：

claude mcp add --transport http artifacta https://mcp.artifacta.io/mcp

首次使用时，客户端会通过 OAuth 动态客户端注册（PKCE）自行注册，并打开浏览器进行授权——无需复制或存储 ak_live_ 密钥。请参阅托管设置指南。

本地 / CI（stdio）

对于无法使用浏览器 OAuth 流程的无头、隔离网络或 CI 环境，可使用 API 密钥通过 stdio 在本地运行此包。在 app.artifacta.io/dashboard/keys 获取密钥，然后将其添加到 MCP 客户端配置中（Claude Desktop、Claude Code、Cursor 或任何 MCP 客户端）：

{
  "mcpServers": {
    "artifacta": {
      "command": "npx",
      "args": ["-y", "@artifacta-mcp/mcp"],
      "env": {
        "ARTIFACTA_API_KEY": "ak_live_..."
      }
    }
  }
}

也可以使用 pipx run artifacta-mcp 运行 Python 实现。

有关配置文件配置方案、路径约束（--allow-path）、破坏性工具门控（--allow-destructive）和故障排除，请参阅各软件包的 README：TypeScript · Python。

工具

工具	描述
whoami	验证凭据；返回租户和套餐信息
store_artifact	从内联内容或本地路径上传工件
request_upload_url / complete_upload	用于大型文件的两阶段预签名上传
get_artifact	按 ID 获取工件元数据
get_artifact_download_url	获取预签名下载 URL（1 小时后过期）
list_artifacts	按会话、Agent 或元数据列出／筛选工件
list_sessions	列出活跃会话
seal_session	封存会话，禁止再添加工件（需启用 --allow-destructive）
create_download_link	创建公开的限时分享链接（需启用 --allow-destructive）
delete_artifact	软删除工件（需启用 --allow-destructive，与 create_download_link 使用相同的门控）
publish_artifact	将工件发布为 artifacta.io/a/{slug} 上的公开页面（Artifact Pages）；幂等，默认不公开列出
unpublish_artifact	下架工件的公开页面；工件本身不受影响；幂等

此外还提供用于 whoami、工件元数据、工件字节内容和会话的 MCP 资源。

安全默认设置：本地文件上传仅限于明确列入 --allow-path 允许列表的路径；对于无法确认写入操作的客户端，破坏性工具（公开分享链接、删除、封存会话）默认隐藏，除非传入 --allow-destructive。publish_artifact 和 unpublish_artifact 是幂等写入操作，不属于破坏性操作，因此不受 --allow-destructive 门控。

托管 OAuth 连接（mcp.artifacta.io）增加了第二层保护：同意页面会授予以下三种范围之一：artifacts:read ⊆ artifacts:write ⊆ artifacts:destroy。所有 13 个工具始终会在 tools/list 中列出；调用令牌未获授权的工具时，会返回代码为 insufficient_scope 的工具错误，并指出缺少的范围。解决方法是重新授权并选择更广泛的范围。范围门控仅适用于托管 OAuth——ak_live_ API 密钥和本地 stdio 仍拥有完整访问权限，改用 --allow-destructive／确认标志进行控制。

框架集成

Python 包提供可选适配器，支持 OpenAI Agents SDK（pip install 'artifacta-mcp[openai-agents]'）和 LangChain/LangGraph（pip install 'artifacta-mcp[langchain]'）。

文档

完整文档见 docs.artifacta.io/mcp/overview。

开发

# TypeScript
cd typescript && npm install && npm test

# Python
cd python && python -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]' && pytest

此仓库从 Artifacta 单体仓库发布；欢迎在此提交问题和 PR。

许可证

MIT — 详见 LICENSE。