内容
# 构件 MCP 服务器
[](https://www.npmjs.com/package/@artifacta-mcp/mcp)
[](https://pypi.org/project/artifacta-mcp/)
[](./LICENSE)
Artifacta 的官方 MCP 服务器 — 一个为 AI 代理设计的构件存储。
代理保存运行输出（文件、报告、数据集、构建结果）以及会话和代理元数据，将它们传递给不同会话，并通过过期下载链接共享。内容哈希重复数据删除意味着重新存储相同的字节是免费的。
在 [官方 MCP 注册表](https://registry.modelcontextprotocol.io) 中列出为 `io.artifacta/mcp`。
两种实现方式具有相同的工具界面、错误合约和路径限制引擎：
| 目录 | 软件包 | 运行时 |
|-----------|---------|---------|
| [`typescript/`](./typescript) | [`@artifacta-mcp/mcp`](https://www.npmjs.com/package/@artifacta-mcp/mcp) | Node 20+ |
| [`python/`](./python) | [`artifacta-mcp`](https://pypi.org/project/artifacta-mcp/) | Python 3.10+ |
## 快速开始
连接最快的方式是使用托管服务器 — 无需安装，无需 API 密钥：
```bash
claude mcp add --transport http artifacta https://mcp.artifacta.io/mcp
```
首次使用时，客户端通过 OAuth 动态客户端注册（PKCE）自行注册，并打开浏览器进行授权 — 无需复制或存储 `ak_live_` 密钥。
请参阅[托管设置指南](https://docs.artifacta.io/mcp/install/claude-code-hosted)。
### 本地 / CI（标准输入输出）
对于无头、隔离或 CI 环境，无法使用浏览器 OAuth 流，本地运行软件包，通过标准输入输出使用 API 密钥。在 [app.artifacta.io/dashboard/keys](https://app.artifacta.io/dashboard/keys) 获取密钥，然后将其添加到 MCP 客户端配置（Claude Desktop、Claude Code、Cursor 或任何 MCP 客户端）：
```json
{
"mcpServers": {
"artifacta": {
"command": "npx",
"args": ["-y", "@artifacta-mcp/mcp"],
"env": {
"ARTIFACTA_API_KEY": "ak_live_..."
}
}
}
}
```
或使用 `pipx run artifacta-mcp` 运行 Python 实现。
请参阅每个软件包的 README，了解配置文件配置文件、路径限制 (`--allow-path`)、破坏性工具门控 (`--allow-destructive`) 和故障排除： [TypeScript](./typescript/README.md) · [Python](./python/README.md)。
## 工具
| 工具 | 描述 |
|------|-------------|
| `whoami` | 验证凭证；返回租户和计划信息 |
| `store_artifact` | 上传来自内联内容或本地路径的构件 |
| `request_upload_url` / `complete_upload` | 用于大文件的两阶段预签名上传 |
| `get_artifact` | 按 ID 获取构件元数据 |
| `get_artifact_download_url` | 获取预签名下载 URL（1 小时过期） |
| `list_artifacts` | 按会话、代理或元数据列出/筛选构件 |
| `list_sessions` | 列出活动会话 |
| `seal_session` | 密封会话，以便不再添加构件 |
| `create_download_link` | 创建公共过期共享链接（在 `--allow-destructive` 后门控） |
| `delete_artifact` | 软删除构件（在写入确认后门控） |
以及用于 `whoami`、构件元数据、构件字节和会话的 MCP 资源。
安全默认值：本地文件上传仅限于显式 `--allow-path` 允许列表，破坏性工具（公共共享链接、删除、会话密封）在未经 `--allow-destructive` 传递的客户端中隐藏。
## 框架集成
Python 软件包为 [OpenAI Agents SDK](./python/examples/openai_agents) (`pip install 'artifacta-mcp[openai-agents]'`) 和 [LangChain/LangGraph](./python/examples/langchain) (`pip install 'artifacta-mcp[langchain]'`) 提供可选适配器。
## 文档
完整文档请参阅 [docs.artifacta.io/mcp/overview](https://docs.artifacta.io/mcp/overview)。
## 开发
```bash
# TypeScript
cd typescript && npm install && npm test
# Python
cd python && python -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]' && pytest
```
该存储库从 Artifacta monorepo 发布；此处欢迎问题和 PR。
## 许可证
MIT — 请参阅 [LICENSE](./LICENSE)。
