402ai mcp
MCP(模型上下文协议)服务器 402ai.net -Lightning-paid API代理。提供具有紧凑/完整配置文件、承载者优先身份验证和动态工具刷新通知的目录感知工具。
当功能发生变化时,请更新我。
特性
- 两种工具配置文件:紧凑型(针对代理进行了优化)或全型(全面的端点覆盖)
- 目录同步:自动跟踪API目录更改
- 承载令牌认证:对预付余额代币的一流支持
- 动态工具更新:通过MCP通知在目录更改时通知客户端
- 智能整合:紧凑型轮廓合并重叠的端点,以减少工具混乱
- TypeScript原生:具有类型安全的完整TypeScript实现
- 全面测试:目录验证、重复数据删除、HTTP处理和多部分上传的单元测试
快速开始
安装```bash
npm install
npm run build
npm test
### 通过stdio运行```bash
ALBOM_BEARER_TOKEN= npm start
NPM包```bash
npm install 402ai-mcp
## 配置
通过环境变量进行配置:
|变量|默认值|描述|
|----------|---------|-------------|
| `ALBOM_BASE_URL` | `https://402ai.net` |API基本URL|
| `ALBOM_BEARER_TOKEN` | _(无)_ |预付余额代币(强烈推荐)|
| `ALBOM_NWC_URI` | _(无)_ |客户端NWC连接URI用于在本地自动支付充值发票|
| `ALBOM_NWC_THRESHOLD_SATS` | `1000` |当API响应报告余额低于此阈值时触发自动关闭|
| `ALBOM_NWC_TOPUP_USD` | `2.00` |每次自动充值的美元金额|
| `ALBOM_NWC_MAX_DAILY` | `10.00` |MCP客户端将在24小时滚动窗口内自动充值的最大美元数|
| `ALBOM_TOOL_PROFILE` | `compact` |刀具轮廓: `compact` 或 `full` |
| `ALBOM_INCLUDE_MODERATION` | `false` (紧凑型), `true` (完整)|包括审核工具|
| `ALBOM_INCLUDE_EMBEDDINGS` | `false` (紧凑型), `true` (完整)|包括嵌入工具|
| `ALBOM_INCLUDE_VIDEO` | `true` |包括视频生成工具|
| `ALBOM_ALLOW_RAW_TOOL` | `false` |暴露 `albom_raw_call` 工具(仅限完整配置文件)|
| `ALBOM_CATALOG_TTL_MS` | `300000` (5分钟)|目录缓存TTL|
| `ALBOM_HTTP_TIMEOUT_MS` | `90000` (90秒)|HTTP请求超时|
| `ALBOM_MAX_RETRIES` | `2` |失败请求的最大重试次数|
| `ALBOM_MAX_UPLOAD_BYTES` | `26214400` (25 MB)|最大上传文件大小|
## 工具配置文件
### 紧凑型配置文件(默认)
针对AI代理进行了优化,工具模糊性最小。将重叠的端点整合到语义工具中:
|工具|目的|映射到端点|
|------|---------|------------------|
| `albom_catalog_get` |获取实时API目录| `/api/v1/catalog` |
| `albom_text_generate` |生成文本补全| `/v1/responses` |
| `albom_image_generate` |生成图像| `/v1/images/generations` |
| `albom_image_edit` |编辑图像| `/v1/images/edits` |
| `albom_audio_speech` |生成语音| `/v1/audio/speech` |
| `albom_video_generate` |生成视频(如果启用)| `/v1/video/generations` |
| `albom_safety_moderate` |内容审核(如果启用)| `/v1/moderations` |
| `albom_embedding_create` |创建嵌入(如果启用)| `/v1/embeddings` |
**整合**:
- 隐藏 `/v1/chat/completions` 支持 `/v1/responses` (相同的模型集)
### 完整剖面
每个目录端点一个工具,实现全面覆盖:
- `albom_openai_chat_completions`
- `albom_openai_responses`
- `albom_openai_images_generations`
- `albom_openai_images_edits`
- `albom_openai_images_variations`
- `albom_openai_audio_speech`
- `albom_openai_audio_transcriptions`
- `albom_openai_embeddings`
- `albom_openai_moderations`
- `albom_openai_video_generations`
- `albom_catalog_get`
- `albom_raw_call` (如果 `ALBOM_ALLOW_RAW_TOOL=true`)
## 认证
### 承载令牌(推荐)
集 `ALBOM_BEARER_TOKEN` 您的预付余额代币。所有请求都将使用 `Authorization: Bearer `.
**获取令牌**:```bash
# 1. Create topup invoice
curl -X POST https://402ai.net/api/v1/topup \
-H "Content-Type: application/json" \
-d '{"amount_sats":1000}'
# 2. Pay invoice with Lightning wallet, then claim
curl -X POST https://402ai.net/api/v1/topup/claim \
-H "Content-Type: application/json" \
-d '{"preimage":""}'
NWC汽车加油
集 ALBOM_NWC_URI 到一个 nostr+walletconnect://... URI,让MCP客户端在本地自动支付充值发票。NWC秘密保留在MCP客户端进程中,永远不会发送到402ai服务器。
当工具响应包括 balance_sats 或 available_sats 在......下面 ALBOM_NWC_THRESHOLD_SATS,MCP客户端将:
POST /api/v1/topup随着{"amount_usd": ALBOM_NWC_TOPUP_USD}- 通过NWC支付退回的发票
pay_invoice POST /api/v1/topup/claim返回的原图- 如果声明返回较新的令牌,则更新内存中的承载令牌
笔记:
- 自动充值仅适用于客户端。NWC URI永远不会触及402ai服务器。
ALBOM_NWC_MAX_DAILY是自动充值的24小时滚动美元支出上限。- 自动充值本身不会引导一个全新的帐户。以有效开头
ALBOM_BEARER_TOKEN,那么NWC可以保持资金平衡。
无令牌(L402流)
如果没有令牌,调用将返回 402 Payment Required 持有闪电发票。MCP服务器将在付款详细信息中显示此错误。
用法示例
使用克劳德桌面
添加 claude_desktop_config.json:```json
{
"mcpServers": {
"402ai": {
"command": "node",
"args": ["/path/to/402ai-mcp/dist/server.js"],
"env": {
"ALBOM_BEARER_TOKEN": "abl_your_token_here",
"ALBOM_NWC_URI": "nostr+walletconnect://...",
"ALBOM_NWC_THRESHOLD_SATS": "1000",
"ALBOM_NWC_TOPUP_USD": "2.00",
"ALBOM_NWC_MAX_DAILY": "10.00",
"ALBOM_TOOL_PROFILE": "compact"
}
}
}
}
### 编程式用法```typescript
import { createAlbomServer } from '402ai-mcp';
const server = createAlbomServer({
baseUrl: 'https://402ai.net',
bearerToken: process.env.ALBOM_BEARER_TOKEN,
toolProfile: 'compact'
});
// Start server
await server.run();
发展
构建```bash
npm run build
## 文件编制纪律
保持 `ARCHITECTURE.md` 和 `WORKLOG.md` 当工具行为、传输假设、身份验证流或部署期望发生变化时,准确无误。
### 测试```bash
npm test # Run all tests
npm run test:watch # Watch mode
开发服务器```bash
npm run dev # Watch and rebuild
npm run start:dev # Run without build
### 烟雾测试(现场API)```bash
ALBOM_BEARER_TOKEN= npm run smoke:live
建筑
核心模块
catalog.ts:获取并验证/api/v1/catalog,检测更改config.ts:环境变量配置和验证dedup.ts:模型集重复数据删除逻辑(Jaccard相似性)httpClient.ts:具有重试逻辑、多部分支持、承载身份验证的HTTP客户端tools/:用于紧凑和完整配置文件的工具实现results.ts:响应规范化和错误处理uploads.ts:文件上传处理(路径和base64)server.ts:MCP服务器实现
目录同步
- 获取
/api/v1/catalog启动时 - 缓存
ALBOM_CATALOG_TTL_MS - 定期刷新和比较
- 发送
notifications/tools/list_changed如果目录更改 - 客户端重新获取工具定义
错误处理
HTTP错误被标准化为MCP友好格式:
402 Payment Required:返回付款详细信息(发票、金额、到期日_in)400 Bad Request:返回验证错误429 Rate Limited:返回信息后重试5xx Server Error:返回错误消息- 网络错误:指数回退自动重试
测试
测试套件包括:
- 目录验证和规范化
- 模型集重复数据删除(Jaccard相似性)
- HTTP错误规范化
- 多部分上传编码(路径+base64)
- 刀具列表更改检测
- 承载令牌身份验证
- 重试逻辑
运行测试:```bash
npm test
## 出版```bash
# 1. Build and test
npm run build
npm test
# 2. Check package contents
npm pack --dry-run
# 3. Publish
npm login
npm version patch # or minor/major
npm publish --access public
项目结构```
.
├── src/
│ ├── catalog.ts # Catalog fetching and tracking
│ ├── config.ts # Environment configuration
│ ├── dedup.ts # Model set deduplication
│ ├── httpClient.ts # HTTP client with retries
│ ├── server.ts # MCP server implementation
│ ├── tools/ # Tool implementations
│ │ ├── compact.ts # Compact profile tools
│ │ ├── full.ts # Full profile tools
│ │ └── shared.ts # Shared tool utilities
│ ├── results.ts # Response normalization
│ ├── uploads.ts # File upload handling
│ ├── types.ts # TypeScript types
│ └── index.ts # Public exports
├── test/ # Test suite
├── scripts/ # Utility scripts
├── dist/ # Compiled output
└── 402AI_MCP_IMPLEMENTATION_SPEC.md # Design spec
Documentation:
└── 402AI_MCP_IMPLEMENTATION_SPEC.md
```
MCP规范
此服务器实现 MCP规范修订版2025-11-25.
支持的功能:
- 工具能力
- 通知功能(
tools/list_changed) - 工具注释(
title,readOnlyHint,idempotentHint) - stdio传输
许可证
MIT-请参阅许可证文件。
贡献
有关最近的更改和发展历史,请参阅WORKLOG.md。