ai-mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,188 @@
+# ai-mcp-server
+
+**Languages:** English | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)
+
+Local MCP bridge: register multiple (api_key, base_url) pairs once, and let your Agent
+automatically discover and route to any model with the right capability (chat, vision,
+reasoning, embedding, image_gen, tts, stt, rerank).
+
+Three entry points:
+- **`ai-mcp`** — CLI (manage endpoints, query models, trigger probes, init wizard)
+- **`ai-mcp-server`** — MCP stdio server, launched by Claude Desktop / Cursor / Cline / Trae
+- **`ai-mcp ui`** — local Web management dashboard (FastAPI + Jinja2, bound to 127.0.0.1)
+
+## Install
+
+### Option 1: uv (recommended)
+
+```bash
+uv tool install ai-mcp-server
+```
+
+### Option 2: Homebrew
+
+```bash
+brew install brianMacao/tap/ai-mcp-server
+```
+
+### Option 3: npm / npx
+
+```bash
+npx ai-mcp-server      # auto-installs uv + Python package
+```
+
+### Option 4: pip
+
+```bash
+pip install ai-mcp-server
+```
+
+## Quickstart
+
+```bash
+# Interactive first-run wizard
+ai-mcp init
+
+# Or step by step:
+ai-mcp endpoint add --name openrouter --base-url https://openrouter.ai/api/v1 --key sk-...
+ai-mcp endpoint probe openrouter
+ai-mcp model list --capability vision
+
+# Start the Web UI
+ai-mcp ui
+# → http://127.0.0.1:8765/
+
+# Start the MCP server (for Claude Desktop, Cursor, etc.)
+ai-mcp-server
+```
+
+## MCP Tools
+
+`ai-mcp-server` exposes 6 MCP tools:
+
+- `usage_guide` — dynamic inventory, capability distribution, and routing guidance.
+- `list_models` — filter models by capability, context length, endpoint, and probe state.
+- `invoke_model` — pass through chat / embedding / image_gen / tts / stt / rerank calls;
+  TTS audio is returned as `audio_base64` inside the JSON body.
+- `model_performance` — inspect recent per-model call counts, success rate, and latency.
+- `refresh_endpoint` — refresh model lists and enqueue asynchronous capability probes.
+- `add_models` — manually register models for endpoints without `/v1/models`, or let an
+  Agent register user-confirmed model features.
+
+## Model Feature Registration
+
+Capabilities use canonical names such as `text_chat`, `vision`, `audio_tts`,
+`audio_stt`, `embedding`, and `rerank`. Common aliases including `tts`, `stt`,
+and `asr` are accepted by manual registration flows and normalized internally.
+
+Static recognition includes these known model ids:
+
+- `seed-tts-2.0` → `audio_tts`
+- `volc.seedasr.sauc.duration` → `audio_stt`
+
+Register model features from the CLI:
+
+```bash
+ai-mcp model add --endpoint volc seed-tts-2.0 --capability audio_tts
+ai-mcp model add --endpoint volc volc.seedasr.sauc.duration --features asr=true
+ai-mcp model add --endpoint volc custom-model --features text_chat=true,context_length=32000
+ai-mcp model override volc custom-model --capability vision=false
+```
+
+Register features from the Web UI:
+
+```bash
+ai-mcp ui
+# Open http://127.0.0.1:8765/
+# Use Models -> manual add, or Overrides -> add/update feature override.
+```
+
+Register features from an MCP client / Agent:
+
+1. Call `usage_guide`.
+2. Use `add_models` with `capabilities` for true capability flags.
+3. Use `feature_overrides` for explicit boolean or context-length overrides.
+
+Example MCP arguments:
+
+```json
+{
+  "endpoint": "volc",
+  "model_ids": ["seed-tts-2.0"],
+  "feature_overrides": {
+    "audio_tts": true,
+    "context_length": 32000
+  }
+}
+```
+
+## Claude Desktop / Trae / Codex Configuration
+
+`ai-mcp init` will auto-detect installed MCP clients and configure them.
+
+### Manual configuration
+
+**Claude Desktop** (`claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "ai-mcp": {
+      "command": "uv",
+      "args": ["run", "--from", "ai-mcp-server", "ai-mcp-server"]
+    }
+  }
+}
+```
+
+**Trae / Trae CN** (project root `.mcp.json`):
+```json
+{
+  "mcpServers": {
+    "ai-mcp": {
+      "command": "uv",
+      "args": ["run", "--from", "ai-mcp-server", "ai-mcp-server"],
+      "transport": "stdio"
+    }
+  }
+}
+```
+
+**Codex Desktop** (`~/.codex/config.toml`):
+```toml
+[mcp_servers.ai-mcp]
+command = "uv"
+args = ["run", "--from", "ai-mcp-server", "ai-mcp-server"]
+```
+
+## Environment Variables
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `AI_MCP_CONFIG_DIR` | Override data/config directory | `~/.ai-mcp-server` |
+| `AI_MCP_DB_PATH` | SQLite database path | `$AI_MCP_CONFIG_DIR/db.sqlite3` |
+| `AI_MCP_MASTER_KEY` | Fernet master key for api_key encryption | auto-generated → system keyring |
+| `AI_MCP_UI_TOKEN` | Access token for Web UI when exposed (`--expose`) | none |
+
+## Development
+
+```bash
+# Clone and set up
+git clone https://github.com/brianMacao/ai-mcp-server
+cd ai-mcp-server
+uv sync
+
+# Run tests
+uv run pytest -q
+
+# Verify against real endpoint
+cp .keys.example .keys   # edit with your keys
+source .keys
+export AI_MCP_CONFIG_DIR="$(pwd)/.data"
+export AI_MCP_MASTER_KEY="$(cat .data/.master_key)"  # first run generates this
+uv run ai-mcp endpoint add --name test --base-url "$EXAMPLE_URL" --key "$EXAMPLE_API_KEY"
+uv run ai-mcp endpoint probe test --capability text_chat -y
+```
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,183 @@
+# ai-mcp-server
+
+**语言：** [English](README.md) | [繁體中文](README.zh-TW.md) | 简体中文
+
+本地 MCP 桥梁：一次登记多组 `(api_key, base_url)`，让 Agent 可以按模型能力自动查询与调用合适的模型，例如 chat、vision、reasoning、embedding、image_gen、tts、stt、rerank。
+
+三个入口：
+
+- **`ai-mcp`**：CLI，用于管理 endpoint、查询模型、触发探活、初始化 MCP client 配置。
+- **`ai-mcp-server`**：MCP stdio server，由 Claude Desktop、Cursor、Cline、Trae 等客户端拉起。
+- **`ai-mcp ui`**：本地 Web 管理界面，FastAPI + Jinja2，默认绑定 `127.0.0.1`。
+
+## 安装
+
+### uv
+
+```bash
+uv tool install ai-mcp-server
+```
+
+### Homebrew
+
+```bash
+brew install brianMacao/tap/ai-mcp-server
+```
+
+### npm / npx
+
+```bash
+npx ai-mcp-server
+```
+
+### pip
+
+```bash
+pip install ai-mcp-server
+```
+
+## 快速开始
+
+```bash
+# 交互式初始设置
+ai-mcp init
+
+# 或逐步设置：
+ai-mcp endpoint add --name openrouter --base-url https://openrouter.ai/api/v1 --key sk-...
+ai-mcp endpoint probe openrouter
+ai-mcp model list --capability vision
+
+# 启动 Web UI
+ai-mcp ui
+# → http://127.0.0.1:8765/
+
+# 启动 MCP server
+ai-mcp-server
+```
+
+## MCP Tools
+
+`ai-mcp-server` 暴露 6 个 MCP tool：
+
+- `usage_guide`：动态 inventory、能力分布与推荐使用方式。
+- `list_models`：按能力、context length、endpoint、探活状态筛选模型。
+- `invoke_model`：透传 chat / embedding / image_gen / tts / stt / rerank 请求；TTS 音频会以 `audio_base64` 放在 JSON body 内返回。
+- `model_performance`：查看近期每个模型的调用次数、成功率与延迟。
+- `refresh_endpoint`：刷新模型列表并入队异步能力探活。
+- `add_models`：为不提供 `/v1/models` 的 endpoint 手动登记模型，或让 Agent 登记用户已确认的模型特性。
+
+## 模型特性登记
+
+能力使用 canonical 名称，例如 `text_chat`、`vision`、`audio_tts`、`audio_stt`、`embedding`、`rerank`。手动登记流程也接受常用别名，例如 `tts`、`stt`、`asr`，并会在内部标准化。
+
+目前静态识别包含：
+
+- `seed-tts-2.0` → `audio_tts`
+- `volc.seedasr.sauc.duration` → `audio_stt`
+
+通过 CLI 登记模型特性：
+
+```bash
+ai-mcp model add --endpoint volc seed-tts-2.0 --capability audio_tts
+ai-mcp model add --endpoint volc volc.seedasr.sauc.duration --features asr=true
+ai-mcp model add --endpoint volc custom-model --features text_chat=true,context_length=32000
+ai-mcp model override volc custom-model --capability vision=false
+```
+
+通过 Web UI 登记：
+
+```bash
+ai-mcp ui
+# 打开 http://127.0.0.1:8765/
+# 在 Models 手动新增，或到 Overrides 新增 / 更新特性覆盖。
+```
+
+通过 MCP client / Agent 登记：
+
+1. 先调用 `usage_guide`。
+2. 若要标记某些能力为 true，调用 `add_models` 并传入 `capabilities`。
+3. 若要明确登记 true / false 或 context length，传入 `feature_overrides`。
+
+MCP 参数示例：
+
+```json
+{
+  "endpoint": "volc",
+  "model_ids": ["seed-tts-2.0"],
+  "feature_overrides": {
+    "audio_tts": true,
+    "context_length": 32000
+  }
+}
+```
+
+## Claude Desktop / Trae / Codex 配置
+
+`ai-mcp init` 会尝试自动检测已安装的 MCP client 并写入配置。
+
+手动配置示例：
+
+**Claude Desktop** (`claude_desktop_config.json`)：
+
+```json
+{
+  "mcpServers": {
+    "ai-mcp": {
+      "command": "uv",
+      "args": ["run", "--from", "ai-mcp-server", "ai-mcp-server"]
+    }
+  }
+}
+```
+
+**Trae / Trae CN**（项目根目录 `.mcp.json`）：
+
+```json
+{
+  "mcpServers": {
+    "ai-mcp": {
+      "command": "uv",
+      "args": ["run", "--from", "ai-mcp-server", "ai-mcp-server"],
+      "transport": "stdio"
+    }
+  }
+}
+```
+
+**Codex Desktop** (`~/.codex/config.toml`)：
+
+```toml
+[mcp_servers.ai-mcp]
+command = "uv"
+args = ["run", "--from", "ai-mcp-server", "ai-mcp-server"]
+```
+
+## 环境变量
+
+| 变量 | 用途 | 默认值 |
+|---|---|---|
+| `AI_MCP_CONFIG_DIR` | 覆盖数据 / 配置目录 | `~/.ai-mcp-server` |
+| `AI_MCP_DB_PATH` | SQLite database 路径 | `$AI_MCP_CONFIG_DIR/db.sqlite3` |
+| `AI_MCP_MASTER_KEY` | Fernet master key，用于加密 api_key | 自动生成并写入系统 keyring |
+| `AI_MCP_UI_TOKEN` | Web UI 对外暴露时使用的 access token | 无 |
+
+## 开发
+
+```bash
+git clone https://github.com/brianMacao/ai-mcp-server
+cd ai-mcp-server
+uv sync
+
+uv run pytest -q
+
+cp .keys.example .keys
+source .keys
+export AI_MCP_CONFIG_DIR="$(pwd)/.data"
+export AI_MCP_MASTER_KEY="$(cat .data/.master_key)"
+uv run ai-mcp endpoint add --name test --base-url "$EXAMPLE_URL" --key "$EXAMPLE_API_KEY"
+uv run ai-mcp endpoint probe test --capability text_chat -y
+```
+
+## License
+
+MIT

package/README.zh-TW.md

@@ -0,0 +1,183 @@
+# ai-mcp-server
+
+**語言：** [English](README.md) | 繁體中文 | [简体中文](README.zh-CN.md)
+
+本地 MCP 橋樑：一次登記多組 `(api_key, base_url)`，讓 Agent 可以按模型能力自動查詢與調用合適的模型，例如 chat、vision、reasoning、embedding、image_gen、tts、stt、rerank。
+
+三個入口：
+
+- **`ai-mcp`**：CLI，用於管理 endpoint、查詢模型、觸發探活、初始化 MCP client 設定。
+- **`ai-mcp-server`**：MCP stdio server，由 Claude Desktop、Cursor、Cline、Trae 等客戶端拉起。
+- **`ai-mcp ui`**：本地 Web 管理介面，FastAPI + Jinja2，預設綁定 `127.0.0.1`。
+
+## 安裝
+
+### uv
+
+```bash
+uv tool install ai-mcp-server
+```
+
+### Homebrew
+
+```bash
+brew install brianMacao/tap/ai-mcp-server
+```
+
+### npm / npx
+
+```bash
+npx ai-mcp-server
+```
+
+### pip
+
+```bash
+pip install ai-mcp-server
+```
+
+## 快速開始
+
+```bash
+# 互動式初始設定
+ai-mcp init
+
+# 或逐步設定：
+ai-mcp endpoint add --name openrouter --base-url https://openrouter.ai/api/v1 --key sk-...
+ai-mcp endpoint probe openrouter
+ai-mcp model list --capability vision
+
+# 啟動 Web UI
+ai-mcp ui
+# → http://127.0.0.1:8765/
+
+# 啟動 MCP server
+ai-mcp-server
+```
+
+## MCP Tools
+
+`ai-mcp-server` 暴露 6 個 MCP tool：
+
+- `usage_guide`：動態 inventory、能力分佈與推薦使用方式。
+- `list_models`：按能力、context length、endpoint、探活狀態篩選模型。
+- `invoke_model`：透傳 chat / embedding / image_gen / tts / stt / rerank 請求；TTS 音訊會以 `audio_base64` 放在 JSON body 內返回。
+- `model_performance`：查看近期每個模型的調用次數、成功率與延遲。
+- `refresh_endpoint`：刷新模型列表並入隊異步能力探活。
+- `add_models`：為不提供 `/v1/models` 的 endpoint 手動登記模型，或讓 Agent 登記使用者已確認的模型特性。
+
+## 模型特性登記
+
+能力使用 canonical 名稱，例如 `text_chat`、`vision`、`audio_tts`、`audio_stt`、`embedding`、`rerank`。手動登記流程也接受常用別名，例如 `tts`、`stt`、`asr`，並會在內部正規化。
+
+目前靜態識別包含：
+
+- `seed-tts-2.0` → `audio_tts`
+- `volc.seedasr.sauc.duration` → `audio_stt`
+
+透過 CLI 登記模型特性：
+
+```bash
+ai-mcp model add --endpoint volc seed-tts-2.0 --capability audio_tts
+ai-mcp model add --endpoint volc volc.seedasr.sauc.duration --features asr=true
+ai-mcp model add --endpoint volc custom-model --features text_chat=true,context_length=32000
+ai-mcp model override volc custom-model --capability vision=false
+```
+
+透過 Web UI 登記：
+
+```bash
+ai-mcp ui
+# 開啟 http://127.0.0.1:8765/
+# 在 Models 手動新增，或到 Overrides 新增 / 更新特性覆寫。
+```
+
+透過 MCP client / Agent 登記：
+
+1. 先調用 `usage_guide`。
+2. 若要標記某些能力為 true，調用 `add_models` 並傳入 `capabilities`。
+3. 若要明確登記 true / false 或 context length，傳入 `feature_overrides`。
+
+MCP 參數範例：
+
+```json
+{
+  "endpoint": "volc",
+  "model_ids": ["seed-tts-2.0"],
+  "feature_overrides": {
+    "audio_tts": true,
+    "context_length": 32000
+  }
+}
+```
+
+## Claude Desktop / Trae / Codex 設定
+
+`ai-mcp init` 會嘗試自動偵測已安裝的 MCP client 並寫入設定。
+
+手動設定範例：
+
+**Claude Desktop** (`claude_desktop_config.json`)：
+
+```json
+{
+  "mcpServers": {
+    "ai-mcp": {
+      "command": "uv",
+      "args": ["run", "--from", "ai-mcp-server", "ai-mcp-server"]
+    }
+  }
+}
+```
+
+**Trae / Trae CN**（專案根目錄 `.mcp.json`）：
+
+```json
+{
+  "mcpServers": {
+    "ai-mcp": {
+      "command": "uv",
+      "args": ["run", "--from", "ai-mcp-server", "ai-mcp-server"],
+      "transport": "stdio"
+    }
+  }
+}
+```
+
+**Codex Desktop** (`~/.codex/config.toml`)：
+
+```toml
+[mcp_servers.ai-mcp]
+command = "uv"
+args = ["run", "--from", "ai-mcp-server", "ai-mcp-server"]
+```
+
+## 環境變數
+
+| 變數 | 用途 | 預設值 |
+|---|---|---|
+| `AI_MCP_CONFIG_DIR` | 覆寫資料 / 設定目錄 | `~/.ai-mcp-server` |
+| `AI_MCP_DB_PATH` | SQLite database 路徑 | `$AI_MCP_CONFIG_DIR/db.sqlite3` |
+| `AI_MCP_MASTER_KEY` | Fernet master key，用於加密 api_key | 自動產生並寫入系統 keyring |
+| `AI_MCP_UI_TOKEN` | Web UI 對外暴露時使用的 access token | 無 |
+
+## 開發
+
+```bash
+git clone https://github.com/brianMacao/ai-mcp-server
+cd ai-mcp-server
+uv sync
+
+uv run pytest -q
+
+cp .keys.example .keys
+source .keys
+export AI_MCP_CONFIG_DIR="$(pwd)/.data"
+export AI_MCP_MASTER_KEY="$(cat .data/.master_key)"
+uv run ai-mcp endpoint add --name test --base-url "$EXAMPLE_URL" --key "$EXAMPLE_API_KEY"
+uv run ai-mcp endpoint probe test --capability text_chat -y
+```
+
+## License
+
+MIT

package/cli.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { spawnSync, execSync } from "node:child_process";
+import { basename } from "node:path";
+import process from "node:process";
+
+const BIN_NAME = basename(process.argv[1] || "ai-mcp");
+const PKG = "ai-mcp-server";
+
+function fail(msg) {
+  process.stderr.write(`\x1b[31m${PKG}\x1b[0m: ${msg}\n`);
+  process.exit(1);
+}
+
+function info(msg) {
+  process.stderr.write(`\x1b[36m${PKG}\x1b[0m: ${msg}\n`);
+}
+
+function hasUv() {
+  try { execSync("uv --version", { stdio: "ignore" }); return true; }
+  catch { return false; }
+}
+
+function isInstalled() {
+  try {
+    const r = execSync("uv tool list --color never", { encoding: "utf-8" });
+    return r.includes(PKG);
+  } catch { return false; }
+}
+
+// -- main --
+if (!hasUv()) {
+  fail("uv is required. Install: https://docs.astral.sh/uv/getting-started/installation/");
+}
+
+if (!isInstalled()) {
+  info(`uv tool install ${PKG} …`);
+  const r = spawnSync("uv", ["tool", "install", PKG], { stdio: "inherit" });
+  if (r.status !== 0) fail(`auto-install failed (exit ${r.status})`);
+}
+
+const userArgs = process.argv.slice(2);
+let entry, args;
+
+switch (BIN_NAME) {
+  case "ai-mcp-ui":
+    entry = "ai-mcp";
+    args = ["ui", ...userArgs];
+    break;
+  case "ai-mcp-server":
+    entry = "ai-mcp-server";
+    args = userArgs;
+    break;
+  default: // "ai-mcp"
+    entry = "ai-mcp";
+    args = userArgs;
+}
+
+const result = spawnSync("uv", ["tool", "run", "--from", PKG, entry, "--", ...args], {
+  stdio: "inherit",
+});
+process.exit(result.status ?? 1);

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "ai-mcp-server",
+  "version": "0.1.0",
+  "description": "Local MCP bridge: unify multi-endpoint model capabilities into a single MCP server + CLI + Web UI",
+  "repository": "github:brianMacao/ai-mcp-server",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "ai-mcp": "./cli.js",
+    "ai-mcp-server": "./cli.js",
+    "ai-mcp-ui": "./cli.js"
+  },
+  "dependencies": {},
+  "files": [
+    "cli.js",
+    "package.json",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "llm",
+    "ai",
+    "model-pool",
+    "openai-compatible"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}