402 AI MCP

402ai mcp

MCP（模型上下文协议）服务器 402ai.net -Lightning-paid API代理。提供具有紧凑/完整配置文件、承载者优先身份验证和动态工具刷新通知的目录感知工具。

当功能发生变化时，请更新我。

特性

• 两种工具配置文件：紧凑型（针对代理进行了优化）或全型（全面的端点覆盖）
• 目录同步：自动跟踪API目录更改
• 承载令牌认证：对预付余额代币的一流支持
• 动态工具更新：通过MCP通知在目录更改时通知客户端
• 智能整合：紧凑型轮廓合并重叠的端点，以减少工具混乱
• TypeScript原生：具有类型安全的完整TypeScript实现
• 全面测试：目录验证、重复数据删除、HTTP处理和多部分上传的单元测试

快速开始

安装

npm install
npm run build
npm test

通过stdio运行

ALBOM_BEARER_TOKEN= npm start

NPM包

npm install 402ai-mcp

配置

通过环境变量进行配置：

工具配置文件

紧凑型配置文件（默认）

针对AI代理进行了优化，工具模糊性最小。将重叠的端点整合到语义工具中：

整合:

• 隐藏 /v1/chat/completions 支持 /v1/responses （相同的模型集）
• 折叠 /v1/audio/translations 进入 albom_audio_transcribe 通过布尔标志

完整剖面

每个目录端点一个工具，实现全面覆盖：

• 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_audio_translations
• 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 .

获取令牌:

# 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客户端将：

1. POST /api/v1/topup 随着 {"amount_usd": ALBOM_NWC_TOPUP_USD}
2. 通过NWC支付退回的发票 pay_invoice
3. POST /api/v1/topup/claim 返回的原图
4. 如果声明返回较新的令牌，则更新内存中的承载令牌

笔记：

• 自动充值仅适用于客户端。NWC URI永远不会触及402ai服务器。
• ALBOM_NWC_MAX_DAILY 是自动充值的24小时滚动美元支出上限。
• 自动充值本身不会引导一个全新的帐户。以有效开头 ALBOM_BEARER_TOKEN，那么NWC可以保持资金平衡。

无令牌（L402流）

如果没有令牌，调用将返回 402 Payment Required 持有闪电发票。MCP服务器将在付款详细信息中显示此错误。

用法示例

使用克劳德桌面

添加 claude_desktop_config.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"
      }
    }
  }
}

编程式用法

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();

发展

构建

npm run build

文件编制纪律

保持 ARCHITECTURE.md 和 WORKLOG.md 当工具行为、传输假设、身份验证流或部署期望发生变化时，准确无误。

测试

npm test              # Run all tests
npm run test:watch    # Watch mode

开发服务器

npm run dev           # Watch and rebuild
npm run start:dev     # Run without build

烟雾测试（现场API）

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服务器实现

目录同步

1. 获取 /api/v1/catalog 启动时
2. 缓存 ALBOM_CATALOG_TTL_MS
3. 定期刷新和比较
4. 发送 notifications/tools/list_changed 如果目录更改
5. 客户端重新获取工具定义

错误处理

HTTP错误被标准化为MCP友好格式：

• 402 Payment Required：返回付款详细信息（发票、金额、到期日_in）
• 400 Bad Request：返回验证错误
• 429 Rate Limited：返回信息后重试
• 5xx Server Error：返回错误消息
• 网络错误：指数回退自动重试

测试

测试套件包括：

• 目录验证和规范化
• 模型集重复数据删除（Jaccard相似性）
• HTTP错误规范化
• 多部分上传编码（路径+base64）
• 刀具列表更改检测
• 承载令牌身份验证
• 重试逻辑

运行测试：

npm test

出版

# 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。