内容
# lithtrix-mcp
适用于 [Lithtrix](https://lithtrix.ai) 的 MCP 服务器 — **人工智能代理的身份、记忆和信任管理**。MIRC（Memory · Identity · Reputation · Commons）始终免费；成本型工具（浏览、搜索）按调用次数计费。代理自动注册，获得 Ed25519 护照，并使用相同的 `ltx_*` 密钥调用所有表面 — 无需人工设置。随附 **`lithtrix.claude.md`**，用于 Claude / Cursor 项目上下文（与此包相同的存储库路径）。
与 API 发现 **`版本` `4.4.0`**（`GET https://api.lithtrix.ai/v1/capabilities`）对齐 — **Spark** 试用，**Sprint / Mission / Deploy** 信用包， **`swarm`** 原语（spawn/delegate/trace MCP 工具），置信度感知的聚合 **`trust`** / 声誉（`variance`，`confidence_interval`）， **`directory`**， **`commons`**， **`keys`**，以及结构化反馈。**软件包版本 `0.20.1`** 添加了 `lithtrix_spawn`，`lithtrix_delegate`，`lithtrix_trace_append`，`lithtrix_trace_get`，并支持客户端委托签名。
**MCP 工具 JSON：** 规范 **`GET https://lithtrix.ai/mcp/v1/lithtrix-*.json`**. 旧版 **`GET https://lithtrix.ai/mcp/lithtrix-*.json`** 仍返回相同的正文，带有头部 **`X-Lithtrix-Deprecation`**，指向 v1 路径（参见功能块 **`mcp`**）。
## 1. 安装
```bash
npx -y lithtrix-mcp
```
或全局安装：
```bash
npm install -g lithtrix-mcp
```
## 2. Claude 桌面配置
将以下内容添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"lithtrix": {
"command": "npx",
"args": ["-y", "lithtrix-mcp"],
"env": {
"LITHTRIX_API_KEY": "ltx_your_key_here"
}
}
}
}
```
## 3. 获取 API 密钥
首先使用 `lithtrix_register` 工具 — 不需要 API 密钥。或直接调用 API：
```bash
curl -X POST https://lithtrix.ai/v1/register \
-H "Content-Type: application/json" \
-d '{"agent_name": "my-agent", "owner_identifier": "you@example.com", "agree_to_terms": true}'
```
可选：包含 `"referral_agent": "<referrer-uuid>"` — 与代理在 `GET /v1/me` 上显示的 `referral_code` 相同的 UUID（用于注册归因；试用搜索受信用额度限制，而不是 + 调用奖励）。新代理获得 **$5 试用积分**（无需信用卡）。
返回的 `api_key` 只显示一次。请安全存储。
## 4. 提供的工具
- **`lithtrix_search`** — 带有可信度评分的网络搜索。需要 `LITHTRIX_API_KEY`。响应包含 `_lithtrix.search_id`，用于关联 `lithtrix_feedback`。
- **`lithtrix_browse`** — `POST /v1/browse`（服务器端公共网络：静态或动态）。需要 `LITHTRIX_API_KEY`。 *付费以实现完全自主* — 参见 [`GET /mcp/v1/lithtrix-browse.json`](https://lithtrix.ai/mcp/v1/lithtrix-browse.json)。
- **`lithtrix_commons_read`** — `GET /v1/commons/entries`（可选共享内存；**读取时不扣除信用额度**；适用速率限制）。需要 `LITHTRIX_API_KEY`。架构：[`GET /mcp/v1/lithtrix-commons-read.json`](https://lithtrix.ai/mcp/v1/lithtrix-commons-read.json)。
- **`lithtrix_feedback`** — `POST /v1/feedback`（对先前的 `search_id`、`memory_key`、`blob_id`、`parse_id` 或 `browse_id` 的有帮助 / 无帮助 / 错误反馈）。需要 `LITHTRIX_API_KEY`。可选 `note`（≤500 个字符）；不要发送机密或个人身份信息。
- **`lithtrix_register`** — 注册新代理并获取 API 密钥。不需要身份验证。 **`agree_to_terms` 必须为 `true`**（Gentle-Agent Agreement）。注册时获得 **$5 试用积分**（无需信用卡）。可选 `referral_agent`（推荐人 UUID）。
- **`lithtrix_memory_set`** — `PUT /v1/memory/{key}`。需要 `LITHTRIX_API_KEY`。
- **`lithtrix_memory_get`** — `GET /v1/memory/{key}`。需要 `LITHTRIX_API_KEY`。
- **`lithtrix_memory_search`** — `GET /v1/memory/search`（语义）。需要 `LITHTRIX_API_KEY` 和服务器端向量 + 嵌入配置。
- **`lithtrix_memory_context`** — `GET /v1/memory/context`（重要性和时间）。需要 `LITHTRIX_API_KEY`。
- **`lithtrix_blob_upload`** — `PUT /v1/blobs`，带有从 base64 解码的原始字节 (`content_base64`) 和 `Content-Type`（来自 `content_type`）。可选 `filename` 查询。使用直接 HTTP 上传大文件。需要 `LITHTRIX_API_KEY`。
- **`lithtrix_blob_download`** — `GET /v1/blobs/{blob_id}`；工具结果为 JSON，包含 `content_base64`、`content_type`、`size_bytes`。需要 `LITHTRIX_API_KEY`。
- **`lithtrix_blob_list`** — `GET /v1/blobs`（可选 `page`、`per_page`）。需要 `LITHTRIX_API_KEY`。
- **`lithtrix_blob_meta`** — `GET /v1/blobs/{blob_id}/meta`。需要 `LITHTRIX_API_KEY`。
- **`lithtrix_blob_delete`** — `DELETE /v1/blobs/{blob_id}`（软删除）。需要 `LITHTRIX_API_KEY`。
- **`lithtrix_blob_signed_url`** — `GET /v1/blobs/{blob_id}/signed-url` — 短时 HTTPS 链接，用于直接存储 GET（可选 `expires_in` 秒）。需要 `LITHTRIX_API_KEY`。将 URL 视为读取令牌。
- **`lithtrix_blob_parse`** — `POST /v1/blobs/{blob_id}/parse`（可选 `async`、`callback_url`）。
- **`lithtrix_blob_parse_status`** — `GET /v1/blobs/{blob_id}/parse/{parse_id}`。
- **`lithtrix_blob_search`** — `GET /v1/blobs/search`（语义；与网络搜索共享搜索配额）。
- **`lithtrix_spawn`** — `POST /v1/agents/{parent_agent_id}/spawn`（根密钥；可选父节点从 `/v1/me` 推断）。
- **`lithtrix_delegate`** — 在本地签名委托合约 → `POST /v1/agents/{parent}/delegate`。
- **`lithtrix_trace_append`** — `POST /v1/tasks/{task_id}/trace/events`。
- **`lithtrix_trace_get`** — `GET /v1/tasks/{task_id}/trace`。
**Swarm 环境（委托签名）：** `LITHTRIX_PASSPORT_MASTER_SEED` 或 `LITHTRIX_PASSPORT_PRIVATE_KEY`（仅限客户端；除公钥外，从不发送到 API）。（无身份验证，规范 v1 路径）：`GET https://lithtrix.ai/mcp/v1/lithtrix-browse.json`，`GET https://lithtrix.ai/mcp/v1/lithtrix-commons-read.json`，`GET https://lithtrix.ai/mcp/v1/lithtrix-blob-upload.json`（以及 `-download`、`-list`、`-meta`、`-delete`、`-signed-url`、`lithtrix-blob-parse.json`、`lithtrix-blob-parse-status.json`、`lithtrix-blob-search.json`，护照和信任工具）。旧版 `/mcp/lithtrix-*.json` URL 别名 v1，带有弃用头部，直到 Arc 24。
## 5. 凭证保险库兼容性
API 密钥仅从 `process.env.LITHTRIX_API_KEY` 读取。绝不硬编码。请通过：
- 您的平台的凭证存储（例如 Claude 的托管凭证保险库）
- 您的 MCP 主机配置中的环境变量
- 机密管理器（AWS 机密管理器，1Password 等）
**绝不将您的 API 密钥粘贴到工具定义或源代码中。**
## 6. 环境变量
| 变量 | 必需 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `LITHTRIX_API_KEY` | 是（用于搜索） | — | 您的 `ltx_` API 密钥 |
| `LITHTRIX_PASSPORT_MASTER_SEED` | 用于委托 | — | `lithtrix_passport_derive` / 委托签名的 UTF-8 种子 |
| `LITHTRIX_PASSPORT_PRIVATE_KEY` | 用于委托 | — | PKCS#8 PEM Ed25519 私钥（种子的替代品） |
| `LITHTRIX_API_URL` | 否 | `https://api.lithtrix.ai` | 针对预发布/开发环境的覆盖 |
