open-index/open-npm huggingface dataset:
npm package: @mcpbay/apps-proxy
Description: Local stdio proxy for MCPBay Apps - enables MCP Apps UI rendering in Claude Desktop
Author: MCPBay
Latest version: 1.0.0

# @mcpbay/apps-proxy

Local stdio proxy for MCPBay Apps - enables MCP Apps UI rendering in Claude Desktop.

## Overview

MCPBay Apps provide rich interactive UIs (like network calculators, dashboards, etc.) that render directly in Claude Desktop. Because Claude Desktop only supports UI rendering for local stdio-based MCP servers, this proxy bridges the gap by connecting to your remote MCPBay Apps endpoint while running locally.

## Requirements

- Node.js 18 or higher
- MCPBay account with Professional tier or higher
- Your MCPBay API key (found in the MCPBay Dashboard)

## Installation

```bash
npm install -g @mcpbay/apps-proxy
```

## Configuration

Add the proxy to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "mcpbay-apps": {
      "command": "mcpbay-apps-proxy",
      "env": {
        "MCPBAY_APPS_URL": "https://YOUR-SERVICE.mcpbay.ai/apps",
        "MCPBAY_API_KEY": "your-api-key-from-dashboard"
      }
    }
  }
}
```

Replace:
- `YOUR-SERVICE` with your MCPBay service slug (e.g., `myserver`)
- `your-api-key-from-dashboard` with your API key from the MCPBay Dashboard

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `MCPBAY_APPS_URL` | Yes | Your MCPBay Apps endpoint URL |
| `MCPBAY_API_KEY` | Yes | Your MCPBay API key for authentication |

## Usage

After configuring Claude Desktop, restart the application. The proxy will automatically connect to your MCPBay Apps endpoint.

To test manually:

```bash
MCPBAY_APPS_URL=https://myserver.mcpbay.ai/apps \
MCPBAY_API_KEY=your-api-key \
mcpbay-apps-proxy
```

## How It Works

1. Claude Desktop launches the proxy as a local stdio MCP server
2. The proxy connects to your remote MCPBay Apps endpoint
3. Tool calls and resource requests are forwarded with authentication
4. UI metadata is passed through, enabling rich interactive experiences

## Troubleshooting

### "Authentication failed: Invalid API key"
- Verify your API key is correct in the MCPBay Dashboard
- Ensure there are no extra spaces or characters in the config

### "Access denied: MCP Apps requires Professional tier"
- MCP Apps is a Professional tier feature
- Upgrade your subscription at mcpbay.ai/dashboard

### Proxy won't start
- Ensure Node.js 18+ is installed: `node --version`
- Check that environment variables are set correctly
- Look for error messages in Claude Desktop logs

## Support

- Documentation: https://docs.mcpbay.ai
- Dashboard: https://mcpbay.ai/dashboard
- Issues: https://github.com/mcpbay/mcpbay-apps-proxy/issues

## License

MIT
npm package: @mcpc-tech/aiyo-acp
Description: ACP runtime integration package for aiyo-compatible
Latest version: 0.0.1-beta.2

# @mcpc-tech/aiyo-acp

ACP integration package for `@mcpc-tech/aiyo`.

Use this package when you want the adapter to boot an **ACP provider runtime** from `defaultACPConfig` or from request-level `extra_body.acpConfig`.

## Install

```bash
pnpm add @mcpc-tech/aiyo-acp
```

## Quick start

```ts
import { Hono } from "hono";
import { createAiyo } from "@mcpc-tech/aiyo-acp";

const adapter = createAiyo({
  defaultModel: "default",
  defaultACPConfig: {
    command: "codebuddy",
    args: ["--acp"],
    session: {
      cwd: process.cwd(),
      mcpServers: [],
    },
  },
});

const app = new Hono();
app.get("/v1/models", adapter.honoHandler());
app.post("/v1/chat/completions", adapter.honoHandler());
app.post("/v1/responses", adapter.honoHandler());
app.post("/v1/messages", adapter.honoHandler());
```

## What this package adds

Compared with the core package, this package wires in:

- ACP-backed `runtimeFactory`
- ACP-backed `listModels`
- ACP tool wrapping through `transformTools`
- ACP dynamic tool-call unwrapping through `normalizeToolCall`

## Request-level ACP config

You can still choose the ACP session per request:

```ts
extra_body: {
  acpConfig: {
    command: "codebuddy",
    args: ["--acp"],
    session: {
      cwd: process.cwd(),
      mcpServers: [],
    },
  },
}
```

## Helper exports

This package also exports these helpers when you want lower-level control:

- `createACPRuntimeFactory`
- `createACPListModelsResolver`
- `createACPToolTransformer`
- `createACPToolCallNormalizer`

It re-exports the core adapter types and helpers from `@mcpc-tech/aiyo`.
npm package: @mcpc-tech/aiyo-cli
Description: CLI launcher for aiyo-compatible
Latest version: 0.0.1-beta.2

# Aiyo CLI

Minimal launcher for local agent integrations backed by the `@mcpc-tech/aiyo` proxy.

## Supported integrations

- `opencode`
- `claude` / `claude-code`

## Usage

From the repo root:

```bash
pnpm install
pnpm run launch opencode
pnpm run launch claude
```

Optional flags:

```bash
pnpm run launch opencode --model default --port 3456 --cwd /path/to/workspace
```

ACP defaults follow the same local config/env convention as the Hono example:

- config file: `aiyo.config.json`
- env: `AIYO_CONFIG`, `ACP_COMMAND`, `ACP_ARGS`, `ACP_CWD`, `ACP_MODEL`, `PORT`, `HOST`
npm package: @mcpc-tech/aiyo-ptc
Description: Programmatic tool calling plugin and Deno runtime for aiyo-compatible
Latest version: 0.0.1-beta.2

# @mcpc-tech/aiyo-ptc

Programmatic Tool Calling (PTC) package for `@mcpc-tech/aiyo`.

This package contains the JavaScript code-execution plugin, the lower-level programmatic tool loop helper, and the Deno-backed runtime factory used to keep execution state across multiple tool calls.

## Install

```bash
pnpm add @mcpc-tech/aiyo-ptc
```

## Quick start

```ts
import { createOpenAI } from "@ai-sdk/openai";
import { createAiyo } from "@mcpc-tech/aiyo";
import { createJavaScriptCodeExecutionPlugin } from "@mcpc-tech/aiyo-ptc";

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY! });

const adapter = createAiyo({
  defaultModel: "gpt-4o-mini",
  runtimeFactory: ({ modelId }) => ({
    model: openai.chat(modelId || "gpt-4o-mini"),
    modelName: modelId || "gpt-4o-mini",
  }),
  listModels: ["gpt-4o-mini"],
  plugins: [
    createJavaScriptCodeExecutionPlugin({
      name: "ptc",
      toolNames: ["read_file", "write_file", "list_dir"],
    }),
  ],
});
```

## Main exports

- `createJavaScriptCodeExecutionPlugin`
- `createProgrammaticToolLoopPlugin`
- `createJavaScriptProgrammaticToolLoopPlugin`
- `buildCodeExecutionSystemPrompt`
- `createDenoCodeExecutionRuntimeFactory`

## When to use which export

- `createJavaScriptCodeExecutionPlugin`: the main high-level PTC entry point
- `createProgrammaticToolLoopPlugin`: lower-level generic helper for custom tool-loop behavior
- `createDenoCodeExecutionRuntimeFactory`: custom runtime wiring when you need to control the execution backend directly

## Architecture

PTC keeps a sandbox session alive across multiple HTTP request / response turns:

1. the model emits a wrapper tool call containing JavaScript
2. the sandbox starts executing that JavaScript
3. each `await tools.some_tool(args)` suspends execution
4. the adapter returns a real tool call to the client
5. the next request with the tool result resumes the same sandbox session

For the full design, see [`../../docs/ptc-architecture.md`](../../docs/ptc-architecture.md).
npm package: @mcpc-tech/ripgrep-napi
Description: Fast text search library powered by Rust ripgrep, providing Node.js bindings via NAPI-RS
Latest version: 0.0.4

# `@napi-rs/ripgrep-napi`

![https://github.com/napi-rs/ripgrep-napi/actions](https://github.com/napi-rs/ripgrep-napi/workflows/CI/badge.svg)

> Template project for writing node packages with napi-rs.

# Usage

1. Click **Use this template**.
2. **Clone** your project.
3. Run `pnpm install` to install dependencies.
4. Run `npx napi rename -n [name]` command under the project folder to rename your package.

## Install this test package

```
pnpm add @napi-rs/ripgrep-napi
```

## Usage

### Build

After `pnpm build` command, you can see `ripgrep-napi.[darwin|win32|linux].node` file in project root. This is the native addon built from [lib.rs](./src/lib.rs).

### Test

With [ava](https://github.com/avajs/ava), run `pnpm test` to testing native addon. You can also switch to another testing framework if you want.

### CI

With GitHub Actions, each commit and pull request will be built and tested automatically in [`node@18`, `node@20`] x [`macOS`, `Linux`, `Windows`] matrix. You will never be afraid of the native addon broken in these platforms.

### Release

Release native package is very difficult in old days. Native packages may ask developers who use it to install `build toolchain` like `gcc/llvm`, `node-gyp` or something more.

With `GitHub actions`, we can easily prebuild a `binary` for major platforms. And with `N-API`, we should never be afraid of **ABI Compatible**.

The other problem is how to deliver prebuild `binary` to users. Downloading it in `postinstall` script is a common way that most packages do it right now. The problem with this solution is it introduced many other packages to download binary that has not been used by `runtime codes`. The other problem is some users may not easily download the binary from `GitHub/CDN` if they are behind a private network (But in most cases, they have a private NPM mirror).

In this package, we choose a better way to solve this problem. We release different `npm packages` for different platforms. And add it to `optionalDependencies` before releasing the `Major` package to npm.

`NPM` will choose which native package should download from `registry` automatically. You can see [npm](./npm) dir for details. And you can also run `pnpm add @napi-rs/ripgrep-napi` to see how it works.

## Develop requirements

- Install the latest `Rust`
- Install `Node.js@16+` which fully supported `Node-API`
- Run `corepack enable`

## Test in local

- pnpm
- pnpm build
- pnpm test

And you will see:

```bash
$ ava --verbose

  ✔ sync function from native code
  ✔ sleep function from native code (201ms)
  ─

  2 tests passed
✨  Done in 1.12s.
```

## Release package

Ensure you have set your **NPM_TOKEN** in the `GitHub` project setting.

In `Settings -> Secrets`, add **NPM_TOKEN** into it.

When you want to release the package:

```
npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease [--preid=<prerelease-id>] | from-git]

git push
```

GitHub actions will do the rest job for you.
npm package: @mcpc-tech/ripgrep-napi-android-arm-eabi
Description: Fast text search library powered by Rust ripgrep, providing Node.js bindings via NAPI-RS
Latest version: 0.0.4

# `@mcpc-tech/ripgrep-napi-android-arm-eabi`

This is the **armv7-linux-androideabi** binary for `@mcpc-tech/ripgrep-napi`
npm package: @mcpc-tech/ripgrep-napi-android-arm64
Description: Fast text search library powered by Rust ripgrep, providing Node.js bindings via NAPI-RS
Latest version: 0.0.4

# `@mcpc-tech/ripgrep-napi-android-arm64`

This is the **aarch64-linux-android** binary for `@mcpc-tech/ripgrep-napi`
npm package: @mcpc-tech/ripgrep-napi-darwin-arm64
Description: Fast text search library powered by Rust ripgrep, providing Node.js bindings via NAPI-RS
Latest version: 0.0.4

# `@mcpc-tech/ripgrep-napi-darwin-arm64`

This is the **aarch64-apple-darwin** binary for `@mcpc-tech/ripgrep-napi`
npm package: @mcpc-tech/ripgrep-napi-darwin-x64
Description: Fast text search library powered by Rust ripgrep, providing Node.js bindings via NAPI-RS
Latest version: 0.0.4

# `@mcpc-tech/ripgrep-napi-darwin-x64`

This is the **x86_64-apple-darwin** binary for `@mcpc-tech/ripgrep-napi`
npm package: @mcpc-tech/ripgrep-napi-freebsd-x64
Description: Fast text search library powered by Rust ripgrep, providing Node.js bindings via NAPI-RS
Latest version: 0.0.4

# `@mcpc-tech/ripgrep-napi-freebsd-x64`

This is the **x86_64-unknown-freebsd** binary for `@mcpc-tech/ripgrep-napi`
npm package: @mcpc-tech/ripgrep-napi-linux-arm-gnueabihf
Description: Fast text search library powered by Rust ripgrep, providing Node.js bindings via NAPI-RS
Latest version: 0.0.4

# `@mcpc-tech/ripgrep-napi-linux-arm-gnueabihf`

This is the **armv7-unknown-linux-gnueabihf** binary for `@mcpc-tech/ripgrep-napi`
npm package: @mcpc-tech/ripgrep-napi-linux-arm64-gnu
Description: Fast text search library powered by Rust ripgrep, providing Node.js bindings via NAPI-RS
Latest version: 0.0.4

# `@mcpc-tech/ripgrep-napi-linux-arm64-gnu`

This is the **aarch64-unknown-linux-gnu** binary for `@mcpc-tech/ripgrep-napi`
npm package: @mcpc-tech/ripgrep-napi-linux-arm64-musl
Description: Fast text search library powered by Rust ripgrep, providing Node.js bindings via NAPI-RS
Latest version: 0.0.4

# `@mcpc-tech/ripgrep-napi-linux-arm64-musl`

This is the **aarch64-unknown-linux-musl** binary for `@mcpc-tech/ripgrep-napi`
npm package: @mcpc-tech/ripgrep-napi-linux-x64-gnu
Description: Fast text search library powered by Rust ripgrep, providing Node.js bindings via NAPI-RS
Latest version: 0.0.4

# `@mcpc-tech/ripgrep-napi-linux-x64-gnu`

This is the **x86_64-unknown-linux-gnu** binary for `@mcpc-tech/ripgrep-napi`
npm package: @mcpc-tech/ripgrep-napi-linux-x64-musl
Description: Fast text search library powered by Rust ripgrep, providing Node.js bindings via NAPI-RS
Latest version: 0.0.4

# `@mcpc-tech/ripgrep-napi-linux-x64-musl`

This is the **x86_64-unknown-linux-musl** binary for `@mcpc-tech/ripgrep-napi`
npm package: @mcpc-tech/ripgrep-napi-wasm32-wasi
Description: Fast text search library powered by Rust ripgrep, providing Node.js bindings via NAPI-RS
Latest version: 0.0.4

# `@mcpc-tech/ripgrep-napi-wasm32-wasi`

This is the **wasm32-wasi-preview1-threads** binary for `@mcpc-tech/ripgrep-napi`
npm package: @mcpc-tech/ripgrep-napi-win32-arm64-msvc
Description: Fast text search library powered by Rust ripgrep, providing Node.js bindings via NAPI-RS
Latest version: 0.0.4

# `@mcpc-tech/ripgrep-napi-win32-arm64-msvc`

This is the **aarch64-pc-windows-msvc** binary for `@mcpc-tech/ripgrep-napi`
npm package: @mcpc-tech/ripgrep-napi-win32-ia32-msvc
Description: Fast text search library powered by Rust ripgrep, providing Node.js bindings via NAPI-RS
Latest version: 0.0.4

# `@mcpc-tech/ripgrep-napi-win32-ia32-msvc`

This is the **i686-pc-windows-msvc** binary for `@mcpc-tech/ripgrep-napi`
npm package: @mcpc-tech/ripgrep-napi-win32-x64-msvc
Description: Fast text search library powered by Rust ripgrep, providing Node.js bindings via NAPI-RS
Latest version: 0.0.4

# `@mcpc-tech/ripgrep-napi-win32-x64-msvc`

This is the **x86_64-pc-windows-msvc** binary for `@mcpc-tech/ripgrep-napi`
npm package: @mcpcn/audio-source-separation-mcp
Description: MCP服务器，用于火山引擎音源分离，支持人声/伴奏分离
Author: 音源分离MCP
Latest version: 1.0.14

# 音源分离 MCP 服务器

基于火山引擎的音源分离MCP服务器，提供人声/伴奏分离功能。

## 功能特性

- 🎵 **人声提取**: 专门的人声分离工具，去除背景音乐
- 🎸 **伴奏提取**: 专门的伴奏分离工具，去除人声
- 🎛️ **模型选择**: 标准模型和降噪增强模型
- 📁 **多格式支持**: wav/mp3/aac等常见音频格式
- 🔧 **灵活配置**: 可自定义输出格式和路径

## 工具说明

### `extract_vocals` - 提取人声
从音频中提取人声，去除背景音乐

**参数:**
- `audio_path` (必需): 音频文件路径
- `use_enhanced_model` (可选): 是否使用降噪增强模型，默认 `false`
- `output_format` (可选): 输出音频格式 (wav/mp3/aac)，默认 `wav`
- `output_path` (可选): 输出文件路径

**示例:**
```javascript
{
  "audio_path": "/path/to/music.mp3",
  "use_enhanced_model": true,
  "output_format": "wav"
}
```

### `extract_accompaniment` - 提取伴奏
从音频中提取伴奏，去除人声

**参数:**
- `audio_path` (必需): 音频文件路径
- `use_enhanced_model` (可选): 是否使用降噪增强模型，默认 `false`
- `output_format` (可选): 输出音频格式 (wav/mp3/aac)，默认 `wav`
- `output_path` (可选): 输出文件路径

**示例:**
```javascript
{
  "audio_path": "/path/to/music.mp3",
  "use_enhanced_model": false,
  "output_format": "wav"
}
```

## 模型说明

- **标准模型** (`use_enhanced_model: false`)
  - `2track_vocal`: 标准人声提取
  - `2track_acc`: 标准伴奏提取
- **降噪增强模型** (`use_enhanced_model: true`)
  - `bs_4track_vocal`: 降噪增强人声提取，效果更好但处理时间更长
  - `bs_4track_acc`: 降噪增强伴奏提取，效果更好但处理时间更长

## 使用限制

- 音频时长: ≤10分钟 (建议 > 5秒)
- 文件大小: ≤100MB
- 仅支持音乐类音频
- 推荐: 采样率≥44.1kHz、双声道
- 支持格式: wav、mp3、aac、flac、m4a

## 安装

```bash
npm install
npm run build
```

## 配置

需要配置火山引擎API凭证环境变量：

```bash
export VOLCENGINE_ACCESS_KEY_ID="your_access_key"
export VOLCENGINE_SECRET_KEY="your_secret_key" 
export VOLCENGINE_APP_KEY="your_app_key"
```

## 启动

不建议用 `npx` 直接启动 MCP 服务器，因为 `npx` 可能向 stdout 输出提示信息，干扰 MCP 的 stdio 握手，导致「MCP 显示失败」。

推荐方式：

- 直接运行构建后的入口：

```bash
node dist/index.js
```

- 或使用包导出的可执行文件（bin）：

```bash
./node_modules/.bin/audio-source-separation-mcp
```

- 开发模式：

```bash
npm run dev
```

## Claude Desktop 配置

在 `claude_desktop_config.json` 中添加：

```json
{
  "mcpServers": {
    "audio-source-separation": {
      "command": "node",
      "args": ["/path/to/audio-source-separation-mcp/dist/index.js"],
      "env": {
        "VOLCENGINE_ACCESS_KEY_ID": "your_access_key",
        "VOLCENGINE_SECRET_KEY": "your_secret_key",
        "VOLCENGINE_APP_KEY": "your_app_key"
      }
    }
  }
}
```

## 技术架构
- 获取key 的方法是地址是：https://www.volcengine.com/docs/6489/71995 详细查看该文档。
- **Node.js + TypeScript**: 核心实现
- **火山引擎 OpenAPI SDK**: API调用和鉴权
- **MCP SDK**: 符合MCP协议
- **Base64编码**: 音频数据传输

## License

MIT License
npm package: @mcpcn/crypto-toolkit
Description: Cryptography & Identity Generation MCP Server - hash generation and UUID tools
Author: Cicatriz
Latest version: 1.0.2

# Crypto Toolkit MCP

加密与标识生成工具 MCP 服务器

## 功能

### 哈希生成（5个工具）
- `generate_md5` - 生成 MD5 哈希
- `generate_sha1` - 生成 SHA-1 哈希
- `generate_sha256` - 生成 SHA-256 哈希
- `generate_sha512` - 生成 SHA-512 哈希
- `generate_hmac` - 生成 HMAC 哈希

### UUID 生成（2个工具）
- `generate_uuid` - 生成 UUID（v1/v4/v5/nil）
- `validate_uuid` - 验证 UUID

## 安装

```bash
npm install
npm run build
```

## 使用

```bash
npm start
```
npm package: @mcpcn/exa-mcp
Description: Exa web search and fetch MCP server for Owlfy
Author: mcpcn
Latest version: 1.0.1

# <div align="center">Owlfy Exa MCP</div>

<div align="center">

Exa web search and page fetch MCP server for Owlfy.

</div>

基于 Exa API 的 MCP 服务器，提供两个工具：

- `web_search_exa`
- `web_fetch_exa`

适合在 Owlfy、Codex、Claude Desktop 或其他支持 MCP `stdio` 的客户端中使用。

如果宿主支持基于配置项自动注入环境变量，可以直接使用仓库内的 `smithery.yaml`，将 `apiKey` 映射到 `EXA_API_KEY`。

## Features

| 功能 | 状态 |
| --- | --- |
| Exa 自然语言网页搜索 | ✅ |
| 批量网页正文抓取 | ✅ |
| 缺少 `EXA_API_KEY` 的明确报错 | ✅ |
| 结果正文清洗与格式化输出 | ✅ |

## Project Structure

```text
owlfy-exa-mcp/
├── src/index.ts
├── dist/index.js
├── owlfy-exa-mcp.mjs
├── package.json
└── README.md
```

## Installation

如果你已经有依赖环境：

```bash
cd /Users/fjc/Desktop/owlfy-exa-mcp
npm install
npm run build
```

当前目录已临时链接到本机现有的 `node_modules`，所以在这台机器上可以直接运行。

## Quick Start

### Direct Run

```bash
cd /Users/fjc/Desktop/owlfy-exa-mcp
EXA_API_KEY=your_exa_api_key node owlfy-exa-mcp.mjs
```

### MCP Config

```json
{
  "mcpServers": {
    "owlfy-exa-mcp": {
      "command": "node",
      "args": [
        "/Users/fjc/Desktop/owlfy-exa-mcp/owlfy-exa-mcp.mjs"
      ],
      "env": {
        "EXA_API_KEY": "your_exa_api_key"
      }
    }
  }
}
```

### Smithery / 可配置环境变量注入

项目已提供 `smithery.yaml`，可将外部配置自动注入到 MCP 进程环境变量：

- `apiKey` -> `EXA_API_KEY`
- `baseUrl` -> `EXA_BASE_URL`

示例配置：

```yaml
apiKey: your_exa_api_key
baseUrl: https://api.exa.ai
```

## Tools

### `web_search_exa`

参数：

- `query`: 自然语言搜索描述
- `numResults`: 返回结果数，默认 `10`

### `web_fetch_exa`

参数：

- `urls`: 需要抓取的 URL 数组
- `maxCharacters`: 每个页面最大提取字符数，默认 `3000`

## Build

```bash
cd /Users/fjc/Desktop/owlfy-exa-mcp
npm run build
```

## Notes

- 运行前必须配置 `EXA_API_KEY`
- 默认 API 地址为 `https://api.exa.ai`
- 如需代理或私有网关，可设置 `EXA_BASE_URL`
npm package: @mcpcn/image-ai-generation-mcp
Description: AI智能生图 MCP 工具 - 基于 Nano Banana Pro API
Latest version: 2.0.4

# AI图片生成 MCP

基于 Nano Banana Pro API 的 AI 智能生图 MCP 工具，支持根据文本描述生成高质量图片。

## 功能特性

- 🎨 **智能生图**: 根据文本提示词生成高质量图片
- 📐 **多种宽高比**: 支持 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, auto
- 🖼️ **高清分辨率**: 支持 1K 分辨率输出
- 🎯 **图片输入**: 支持最多 8 张输入图片作为参考或转换
- 📤 **格式选择**: 支持 PNG 和 JPG 输出格式
- ☁️ **云端生成**: 图片直接在云端生成并返回 URL

## 安装

```bash
npm install
npm run build
```

## 配置

需要设置环境变量 `KIE_API_KEY`:

```bash
export KIE_API_KEY=your_api_key_here
```

获取 API Key: 访问 [https://kie.ai/api-key](https://kie.ai/api-key)

## 使用方法

### 工具 1: generate-image

创建图片生成任务。

**参数:**
- `prompt` (必需): 图片生成提示词，详细描述想要生成的图片内容（最多20000字符）
- `image_input` (可选): 输入图片URL数组，最多8张，用于图片转换或作为参考
  - 支持格式: jpeg, png, webp
  - 单个文件最大: 30MB
- `aspect_ratio` (可选): 图片宽高比，默认 '1:1'
  - 可选值: '1:1', '2:3', '3:2', '3:4', '4:3', '4:5', '5:4', '9:16', '16:9', '21:9', 'auto'
- `resolution` (可选): 图片分辨率，默认 '1K'
  - 可选值: '1K'（目前仅支持此选项）
- `output_format` (可选): 输出格式，默认 'png'
  - 可选值: 'png', 'jpg'

**示例:**
```json
{
  "prompt": "一只可爱的橘猫坐在窗台上看着外面的雪景",
  "aspect_ratio": "16:9",
  "resolution": "1K",
  "output_format": "png"
}
```

**带图片输入的示例:**
```json
{
  "prompt": "将这张图片转换为水彩画风格",
  "image_input": ["https://example.com/image.jpg"],
  "aspect_ratio": "1:1",
  "resolution": "1K"
}
```

**返回格式:**
```json
{
  "success": true,
  "message": "图片生成任务已创建",
  "taskId": "281e5b0*********************f39b9",
  "prompt": "提示词",
  "aspect_ratio": "16:9",
  "resolution": "1K",
  "output_format": "png",
  "tip": "请使用 query-task 工具查询任务进度和结果"
}
```

### 工具 2: query-task

查询图片生成任务的状态和进度。

**参数:**
- `taskId` (必需): 任务ID，由 `generate-image` 返回

**示例:**
```json
{
  "taskId": "281e5b0*********************f39b9"
}
```

**返回格式:**
```json
{
  "taskId": "281e5b0*********************f39b9",
  "state": "success",
  "model": "nano-banana-pro",
  "elapsedSeconds": 45,
  "imageUrl": "https://static.aiquickdraw.com/tools/example/1763662100739_DlBXJvdR.png",
  "failCode": null,
  "failMsg": null,
  "createdAt": "2026-01-22T03:00:00.000Z",
  "completedAt": "2026-01-22T03:00:45.000Z"
}
```

**状态说明:**
- `waiting`: 任务排队中
- `success`: 任务完成，可从 `imageUrl` 获取图片
- `fail`: 任务失败，查看 `failMsg` 了解原因


## 提示词建议

为了获得更好的生成效果，建议：

1. **详细描述**: 包含主体、环境、光线、色彩等细节
2. **明确风格**: 指定艺术风格或参考风格
3. **构图说明**: 描述视角、景深、焦点等
4. **情感氛围**: 表达想要传达的情绪和氛围

**好的提示词示例:**
- "一个穿着红色连衣裙的女孩在樱花树下跳舞，柔和的阳光透过花瓣洒下，梦幻的粉色调，电影级构图"
- "赛博朋克风格的东京街道，霓虹灯闪烁，雨后湿润的地面反射着五彩的光芒，广角镜头"
- "油画风格的山间小屋，秋天的金黄色树叶，温暖的壁炉光从窗户透出，宁静祥和的氛围"

## API 说明

本工具使用 Nano Banana Pro API，详细文档请参考: [https://kie.ai/api-key](https://kie.ai/api-key)

## 开发

```bash
# 开发模式
npm run dev

# 构建
npm run build

# 清理
npm run clean
```

## 许可证

MIT
npm package: @mcpcn/image-recognition-mcp
Description: MCP服务器用于图片识别和信息提取
Latest version: 1.0.4

# 通用图片识别 MCP 服务器

基于阿里云百炼平台千问视觉模型的通用图片识别 MCP 服务器，支持识别图片中的文字和信息内容。

## 功能特性

- **通用图片识别**: 识别图片中的所有文字内容和关键信息
- **自定义提示词**: 支持自定义识别提示词，满足不同需求
- **多种图片格式**: 支持URL和base64两种图片输入方式
- **灵活配置**: 支持自定义图片像素参数

## 安装配置

### 1. 安装依赖

```bash
npm install
```

### 2. 环境变量配置

设置阿里云百炼API Key：

```bash
export DASHSCOPE_API_KEY="your-api-key-here"
```

或在使用时临时设置：

```bash
DASHSCOPE_API_KEY="your-api-key" npm start
```

### 3. 构建项目

```bash
npm run build
```

## 使用方法

### 启动服务器

```bash
npm start
```

### 在 Claude Desktop 中配置

在 Claude Desktop 的配置文件中添加：

```json
{
  "mcpServers": {
    "image-recognition": {
      "command": "node",
      "args": ["/path/to/image-recognition-mcp/dist/index.js"],
      "env": {
        "DASHSCOPE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## 工具说明

### recognize_image - 通用图片识别工具

支持识别各种类型的图片内容：

**参数说明：**
- **image_url**: 图片URL地址
- **image_data**: 图片base64数据（可选）
- **custom_prompt**: 自定义识别提示词（可选）
- **min_pixels/max_pixels**: 图片像素参数（可选）

## 使用示例

### 📝 基本文字识别

```
请识别这张图片中的文字：https://example.com/image.jpg
```

### 🎯 自定义识别需求

```
请识别这张名片并提取联系信息，图片：https://example.com/business-card.jpg
```

### 📋 发票信息提取

```
请提取这张发票的详细信息，包括金额、税额、开票日期等：https://example.com/invoice.jpg
```

### 📊 表格数据识别

```
请识别这个表格的所有数据：https://example.com/table.jpg
```

### 🆔 证件信息识别

```
请识别这张身份证的信息：https://example.com/id-card.jpg
```

## 技术栈

- **MCP SDK**: Model Context Protocol 框架
- **OpenAI SDK**: 兼容阿里云百炼API
- **TypeScript**: 类型安全开发
- **千问视觉模型**: qwen-vl-ocr-latest

## 开发说明

### 项目结构

```
src/
├── index.ts              # 主服务器文件
├── tools/
│   └── image-recognition.ts  # 图片识别工具实现
└── types/
    └── index.ts          # 类型定义
```

### 开发模式

```bash
npm run dev  # 监听文件变化并自动重新构建
```

## 注意事项

1. **API密钥**: 需要有效的阿里云百炼API Key
2. **图片访问**: 图片URL需要可公开访问
3. **Base64格式**: Base64图片数据需要包含数据头（data:image/...）
4. **图片大小**: 模型对图片大小有限制，建议合理设置像素参数

## 更新日志

### v1.0.0
- ✨ 通用图片识别功能
- 🛠️ 自定义提示词支持
- 📤 多种图片输入方式
- ⚙️ 灵活参数配置
npm package: @mcpcn/image-understanding
Description: Analyze and interpret images with the Zhipu AI GLM vision models
Latest version: 1.0.4

# Image Understanding MCP

An MCP server that uses the Zhipu AI GLM vision models to analyze and describe images.

## Features

- Supports multiple GLM vision models (glm-4v-plus, glm-4v, glm-4v-flash)
- Flexible generation controls (temperature, max tokens, etc.)
- Robust error handling with clear messaging
- TypeScript-based implementation with strong typing

## Environment Variables

- `ZHIPU_API_KEY` or `GLM_API_KEY`: Required, Zhipu AI API key
- `GLM_VISION_MODEL`: Optional, override the default model (defaults to `glm-4v-plus`)

## Install & Build

```bash
npm install
npm run build
```

## Run

```bash
# Run the compiled entry
npm start
# Or invoke the CLI wrapper
image-understanding-mcp
```

## MCP Client Configuration

Example entry for Claude Desktop:

```json
{
  "mcpServers": {
    "image-understanding": {
      "command": "node",
      "args": ["/absolute/path/to/this/project/dist/index.js"],
      "env": {
        "ZHIPU_API_KEY": "your-zhipu-key"
      }
    }
  }
}
```

## Exposed Tool

### image_understanding

Analyze an image via the GLM vision model suite.

**Parameters**:
- `imageUrl` (required): Image URL
- `prompt` (optional): Instruction for the analysis, defaults to “Describe this image in detail.”
- `model` (optional): Model id, default `glm-4v-plus`
- `temperature` (optional): 0-1, default 0.7
- `maxTokens` (optional): 1-4096, default 1024

**Supported Models**:
- `glm-4v-plus`: Highest fidelity, best for complex scenes (max 4096 tokens)
- `glm-4v`: Balanced performance/cost (max 2048 tokens)
- `glm-4v-flash`: Fastest inference for simple analysis (max 1024 tokens)

## Project Layout

```
src/
├── index.ts          # MCP server entry
├── config.ts         # Model options
├── types.ts          # Shared types
└── tool.ts           # Tool implementation
```

## Compatibility

- Node.js >= 18
- `@modelcontextprotocol/sdk` v1
npm package: @mcpcn/image-understanding-mcp
Description: 智谱GLM-4V-Plus-0111 图片内容理解MCP工具
Latest version: 1.0.3

# 智谱图片理解 MCP（可配置模型）

基于智谱AI 视觉大模型的图片内容理解 MCP（Model Context Protocol）工具，支持通过 URL 上传图片并进行 AI 分析。默认模型为 `GLM-4V-Plus-0111`，可通过环境变量覆盖。

## 功能特性

- 🖼️ **图片内容分析**: 使用智谱视觉模型（默认：GLM-4V-Plus-0111）分析图片内容
- 🌐 **URL支持**: 支持HTTP/HTTPS图片链接和base64编码
- 🎯 **可配置模型**: 通过环境变量 `GLM_VISION_MODEL` 配置默认模型
- ⚙️ **灵活配置**: 可自定义分析提示词、温度参数、最大token数等
- 🔐 **安全认证**: 通过环境变量管理API密钥
- 📊 **详细反馈**: 提供token使用情况和错误信息

## 支持的模型

默认支持：

- `GLM-4V-Plus-0111`：Plus 版本图像理解能力，适用于需要较高质量图像理解与更强推理的场景。

## 安装和设置

### 1. 安装依赖

```bash
npm install
```

### 2. 构建项目

```bash
npm run build
```

### 3. 设置API密钥

从[智谱AI开放平台](https://bigmodel.cn/)获取 API 密钥，然后设置环境变量：

```bash
# 方式1：设置GLM_API_KEY
export GLM_API_KEY=your_api_key_here

# 方式2：设置ZHIPU_API_KEY
export ZHIPU_API_KEY=your_api_key_here
```

### 4. 启动MCP服务器

```bash
npm start
```

## 使用方法

### 可用工具

#### `analyze_image` - 分析图片内容

分析指定URL的图片内容，返回AI生成的描述。

**参数**:
- `imageUrl` (必需): 图片的URL地址
- `prompt` (可选): 分析提示词，默认为"请详细描述这张图片的内容"
- `model` (可选): 使用的模型，默认来自环境变量或配置，通常为 "GLM-4V-Plus-0111"
- `temperature` (可选): 随机性控制(0-1)，默认0.7
- `maxTokens` (可选): 最大输出token数，默认1024

**示例**:
```json
{
  \"name\": \"analyze_image\",
  \"arguments\": {
    \"imageUrl\": \"https://example.com/image.jpg\",
    \"prompt\": \"这张图片中有什么动物？\",
    \"model\": \"GLM-4V-Plus-0111\"
  }
}
```

## 配置示例

### Claude Desktop配置

在`claude_desktop_config.json`中添加：

```json
{
  \"mcpServers\": {
    \"image-understanding\": {
      \"command\": \"node\",
      \"args\": [\"/path/to/image-understanding-mcp/dist/index.js\"],
      \"env\": {
        \"GLM_API_KEY\": \"your_api_key_here\"
      }
    }
  }
}
```

## API响应格式

### 成功响应
```json
{
  \"success\": true,
  \"analysis\": \"图片分析结果...\",
  \"model\": \"GLM-4V-Plus-0111\",
  \"tokenUsage\": {
    \"promptTokens\": 150,
    \"completionTokens\": 200,
    \"totalTokens\": 350
  }
}
```

### 错误响应
```json
{
  \"success\": false,
  \"error\": \"错误信息\",
  \"model\": \"GLM-4V-Plus-0111\"
}
```

## 开发脚本

- `npm run build` - 构建TypeScript代码
- `npm run dev` - 开发模式（监听文件变化）
- `npm start` - 启动MCP服务器
- `npm run clean` - 清理构建文件

## 错误处理

工具包含完善的错误处理机制：

- **参数验证**: 使用Zod进行输入参数验证
- **网络错误**: 处理API请求超时和网络连接问题
- **认证错误**: 识别API密钥无效、权限不足等问题
- **限流处理**: 识别API调用频率限制
- **服务器错误**: 处理API服务器内部错误

## 注意事项

1. **API密钥安全**: 请妥善保管您的API密钥，不要在代码中硬编码
2. **计费与额度**: 具体计费与额度以智谱AI官网为准
3. **图片格式**: 支持常见的图片格式（JPEG、PNG、GIF等）
4. **图片大小**: 建议图片大小不超过10MB
5. **URL访问**: 确保图片URL可以公开访问，不需要特殊权限

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request来改进这个工具。

## 相关链接

- [智谱AI开放平台](https://bigmodel.cn/)
- [GLM-4V API文档](https://docs.bigmodel.cn/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
## 配置默认模型

通过环境变量覆盖默认视觉模型：

```bash
export GLM_VISION_MODEL=GLM-4V-Plus-0111
```

若将来要切换为其它兼容模型，只需修改该环境变量，无需改代码。
npm package: @mcpcn/image-vision-mcp
Description: 合并版 MCP：图片文字提取 + 图片内容理解
Latest version: 1.0.6

# 合并版 MCP：图片文字提取 + 图片内容理解

本项目将原有两个 MCP：
- `图片文字提取`（阿里云百炼 Qwen OCR）
- `图片内容理解`（智谱 GLM 视觉模型）

合并为一个 MCP 服务器，统一暴露两个工具，便于在同一次连接中调用。

## 环境变量
- `DASHSCOPE_API_KEY`：阿里云百炼 API Key（用于图片文字提取）
- `ZHIPU_API_KEY` 或 `GLM_API_KEY`：智谱 AI API Key（用于图片内容理解）
- `GLM_VISION_MODEL`：可选，自定义默认视觉模型（默认 `GLM-4V-Plus-0111`）

未配置对应密钥时，相关工具会返回友好错误，不影响服务器启动。

## 安装与构建
```bash
npm install
npm run build
```

## 运行
```bash
# 直接运行已构建的入口
npm start
# 或作为可执行命令（安装到全局/本地 bin 后）
image-vision-mcp
```

## 在 MCP 客户端中配置
以 Claude Desktop 为例，在其 MCP 配置中添加：
```json
{
  "mcpServers": {
    "image-vision": {
      "command": "node",
      "args": ["/绝对路径/到/本项目/dist/index.js"],
      "env": {
        "DASHSCOPE_API_KEY": "your-dashscope-key",
        "ZHIPU_API_KEY": "your-zhipu-key"
      }
    }
  }
}
```

## 暴露的工具
- 工具名：`ocr_extract_text`
  - 参数：`image_url`，`custom_prompt?`，`min_pixels?`，`max_pixels?`
  - 功能：使用阿里云百炼Qwen OCR提取图片文字。
- 工具名：`image_understanding`
  - 参数：`imageUrl`，`prompt?`，`model?`，`temperature?`，`maxTokens?`
  - 功能：使用智谱视觉模型进行图片内容理解与分析。

## 目录结构
- `src/index.ts`：单一 MCP 服务器入口，同时注册两个工具。
- `src/tools/ocr-qwen.ts`：图片文字提取工具实现（Qwen OCR）。
- `src/tools/understanding-glm.ts`：图片内容理解工具实现（GLM）。
- `src/types.ts`：通用类型定义。
- `src/config.ts`：模型默认值与枚举。

## 兼容性
- Node.js >= 18
- `@modelcontextprotocol/sdk` v1 接口

## 迁移说明
源项目：
- /Users/fengjinchao/Desktop/mcp/skills/typescript/图片文字提取
- /Users/fengjinchao/Desktop/mcp/skills/typescript/图片内容理解

两者的核心逻辑已整合并最小改动保留；若后续要合并更多模型，只需在 `src/tools` 下新增实现，并在 `src/index.ts` 增加工具注册即可。