From 41f6e2ea9548e83ba34bba3f80fdf7912495d2c6 Mon Sep 17 00:00:00 2001 From: John Doe Date: Wed, 6 May 2026 03:28:59 +0000 Subject: [PATCH] Add LICENSE, AGENTS.md, smithery.yaml, English README intro and richer metadata MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - LICENSE (MIT) so the published npm package and Smithery deployments ship with explicit license terms. - AGENTS.md is the dedicated agent-facing playbook covering the hosted Streamable-HTTP endpoint at https://uapis.cn/mcp, npm/stdio install, per-agent wiring snippets (Claude / Cursor / etc.), tool overview, auth, rate-limits, and links to all UAPI discovery surfaces. - smithery.yaml + Dockerfile so the server can be one-click deployed on smithery.ai via the published npm package. - README.md gains an English summary block with badges (npm version, Node, MCP protocol version, license) and a wiring matrix; the existing 中文 documentation is preserved beneath the new section. - package.json: human-readable English description, homepage now points to https://uapis.cn/mcp, license=MIT, plus npm-search-friendly keywords (mcp, model-context-protocol, uapi, public-api, ...). - manifest.json: same keywords/description treatment so the manifest is consistent with package.json and surfaces well in MCP registries. Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- AGENTS.md | 130 ++++++++++++++++++++++++++++++++++++++++++++++++++ Dockerfile | 16 +++++++ LICENSE | 21 ++++++++ README.md | 53 +++++++++++++++++++- manifest.json | 25 ++++++++-- package.json | 28 +++++++++-- smithery.yaml | 33 +++++++++++++ 7 files changed, 296 insertions(+), 10 deletions(-) create mode 100644 AGENTS.md create mode 100644 Dockerfile create mode 100644 LICENSE create mode 100644 smithery.yaml diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b484ec3 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,130 @@ +# AGENTS.md — uapi-mcp + +This file tells AI coding agents (Codex, Claude Code, Cursor, OpenCode, Gemini, +etc.) what this repository is and how to wire up the **UAPI MCP server**. + +## What this repo is + +The official MCP (Model Context Protocol) server for the public API platform +[uapis.cn](https://uapis.cn). It exposes **100+ UAPI endpoints** — network +lookups, text utilities, image processing, social-platform queries, +translation, search, weather, time, OCR — as MCP tools that any MCP-aware +AI agent can call directly. + +## Hosted server (recommended) + +A managed Streamable-HTTP MCP server is already running. Most agents only +need this one URL: + +``` +https://uapis.cn/mcp +``` + +Discovery shortcuts: + +- Server card: +- WebMCP descriptor: +- Agent card: + +Wiring it into common agents: + +```jsonc +// Claude Desktop / Claude Code (claude_desktop_config.json) +{ + "mcpServers": { + "uapi": { + "transport": "streamable-http", + "url": "https://uapis.cn/mcp" + } + } +} +``` + +```jsonc +// Cursor (.cursor/mcp.json) +{ + "mcpServers": { + "uapi": { + "url": "https://uapis.cn/mcp" + } + } +} +``` + +For paid endpoints, set the UAPI key once via the `X-API-Key` header +(MCP servers may forward `mcpAuth.bearer` to this header — see the +server card for details). + +## Local install (npm) + +The same server is published on npm and runs over stdio for local agents: + +```bash +# Run directly (no install) +npx -y uapi-mcp start --mode dynamic + +# Or install globally +npm i -g uapi-mcp +uapi-mcp start --mode dynamic +``` + +Stdio config example: + +```jsonc +{ + "mcpServers": { + "uapi": { + "command": "npx", + "args": ["-y", "uapi-mcp", "start", "--mode", "dynamic"] + } + } +} +``` + +## Build from source + +```bash +git clone https://github.com/AxT-Team/uapi-mcp +cd uapi-mcp +npm install +npm run build +node ./bin/mcp-server.js start --mode dynamic +``` + +## Available tools + +The server exposes one MCP tool per UAPI operation. Operation IDs and +schemas come straight from the OpenAPI document at +, so the tool list mirrors the REST API +1-to-1. Examples: + +- `get_misc_weather` — current weather + forecast for a city +- `get_network_whois` — WHOIS lookup +- `get_text_md5` / `post_text_md5_verify` — MD5 hashing & verification +- `post_image_compress` — image compression +- `post_translate_text` — text translation + +Run `npx uapi-mcp tools list` (or the equivalent MCP `tools/list` call) +to see the full list at runtime. + +## Authentication + +- Free-tier endpoints work with no auth. +- Paid endpoints need an `X-API-Key`. Get one at + . +- For OAuth-style flows, see + . + +## Rate limits + +UAPI returns standard rate-limit headers +(`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`). The MCP +server forwards them on tool errors so the agent can back off properly. + +## Related repos + +- Skills bundle: +- Browser SDK: +- TypeScript SDK: +- Python SDK: +- CLI: diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..1406534 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,16 @@ +# Dockerfile for uapi-mcp. +# Used by the Smithery deployment manifest (smithery.yaml). +FROM node:20-bullseye-slim + +WORKDIR /app + +ENV NODE_ENV=production +ENV CI=1 + +# Install just the npm package (and its deps). The package's prepublishOnly +# script bundles the server into ./bin/mcp-server.js, so a fresh `npm install` +# of the published version pulls down a runnable build. +RUN npm install -g uapi-mcp@latest + +# Smithery runs MCP servers over stdio. +ENTRYPOINT ["uapi-mcp", "start", "--mode", "dynamic"] diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..4e7b5fa --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 AxT-Team / UAPI + +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. diff --git a/README.md b/README.md index f89d19e..9b92675 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,60 @@ ![Banner](https://raw.githubusercontent.com/AxT-Team/uapi-mcp/main/banner.png?v=20260309-4) +[![npm version](https://img.shields.io/npm/v/uapi-mcp?style=flat-square)](https://www.npmjs.com/package/uapi-mcp) [![Node.js](https://img.shields.io/badge/Node.js-18+-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org/) [![Docs](https://img.shields.io/badge/Docs-uapis.cn-2EAE5D?style=flat-square)](https://uapis.cn/docs) -[![MCP](https://img.shields.io/badge/MCP-Uapi%20Mcp-7C3AED?style=flat-square)](https://modelcontextprotocol.io/) +[![MCP](https://img.shields.io/badge/MCP-2025--06--18-7C3AED?style=flat-square)](https://modelcontextprotocol.io/) +[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE) -Uapi Mcp 是 `uapis.cn` 的官方 MCP Server，用来把 UAPI 的搜索、翻译、图像、文本处理和网页解析能力整理成统一入口，方便接入支持 MCP 的客户端。 +> Official MCP (Model Context Protocol) server for the +> [uapis.cn](https://uapis.cn) public API platform. Exposes **100+ UAPI +> endpoints** — network lookups, text utilities, image processing, +> social-platform queries, translation, search — as agent tools over +> Streamable HTTP and stdio. + +## English summary + +**Hosted server** (managed, recommended for most agents): + +```text +https://uapis.cn/mcp +``` + +| Wiring | Snippet | +| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Claude Desktop / Claude Code | `{"mcpServers":{"uapi":{"transport":"streamable-http","url":"https://uapis.cn/mcp"}}}` | +| Cursor (`.cursor/mcp.json`) | `{"mcpServers":{"uapi":{"url":"https://uapis.cn/mcp"}}}` | +| Stdio (npx) | `npx -y uapi-mcp start --mode dynamic` | + +**Local install** (stdio, fully offline): + +```bash +npx -y uapi-mcp start --mode dynamic +# or +npm install -g uapi-mcp && uapi-mcp start --mode dynamic +``` + +Authentication: + +- Free-tier endpoints work with no key. +- Paid endpoints need `X-API-Key`. Get a key at + [uapis.cn/console](https://uapis.cn/console). + +Discovery surfaces: + +- Server card: +- WebMCP descriptor: +- OpenAPI spec: +- LLM context bundle: + +See [`AGENTS.md`](./AGENTS.md) for the full agent-facing playbook. + +--- + +## 中文说明 + +Uapi Mcp 是 `uapis.cn` 的官方 MCP Server，把 UAPI 的搜索、翻译、图像、文本处理、网页解析能力整合成一个标准化接口，支持任何 MCP 协议客户端。 ## 快速开始 diff --git a/manifest.json b/manifest.json index 7ff7937..da0cdb4 100644 --- a/manifest.json +++ b/manifest.json @@ -2,14 +2,25 @@ "author": { "name": "UAPI" }, - "description": "Uapi Mcp 是 uapis.cn 的官方MCP。它把 UAPI 的搜索、翻译、图像、文本处理和网页解析能力整理成统一的 MCP Server，让你的ai拥有无限的能力~", + "description": "Official MCP server for uapis.cn — exposes 100+ public-API endpoints (network, text, image, social, translation, search) as agent tools.", "display_name": "Uapi Mcp", "icon": "banner.png", "keywords": [ "uapi", - "mcp" + "uapis", + "uapis.cn", + "mcp", + "model-context-protocol", + "agent", + "llm", + "public-api", + "free-api", + "rest-api", + "openapi", + "streamable-http", + "stdio" ], - "long_description": "Uapi Mcp 是 uapis.cn 的官方MCP。它把 UAPI 的搜索、翻译、图像、文本处理和网页解析能力整理成统一的 MCP Server，让你的ai拥有无限的能力~", + "long_description": "uapi-mcp is the official MCP (Model Context Protocol) server for the uapis.cn public API platform. It exposes 100+ free and paid REST endpoints — network lookups, text & image utilities, social platform queries, translation, and search — as MCP tools, so any MCP-aware AI agent (Claude, Cursor, OpenCode, Codex, etc.) can call them directly. Streamable-HTTP transport is hosted at https://uapis.cn/mcp; the same server runs locally over stdio via npx.", "manifest_version": "0.3", "name": "uapi-mcp", "prompts": [], @@ -418,5 +429,9 @@ "name": "-post-sensitive-word-quick-check", "description": "敏感词检测（快速）\n\n在你的社区或应用中，需要过滤不适合展示的内容时，这个接口可以帮你快速完成检测。\n\n## 功能概述\n\n这个接口可以识别文本中的敏感词，并返回是否命中、命中词列表等结果，适合用于评论区、社区、论坛和内容发布场景。\n\n### 主要特性\n\n- **快速检测**：能够一次处理整段文本中的多个命中内容\n- **简繁体支持**：支持简体中文、繁体中文和混合文本检测\n- **结果直观**：返回清晰的检测结果，方便直接接入审核流程\n- **响应稳定**：适合日常内容审核和批量检查场景\n\n无论是论坛、社交平台还是评论系统，这个接口都能帮你快速构建内容审核功能。" } - ] -} \ No newline at end of file + ], + "homepage": "https://uapis.cn/mcp", + "repository": "https://github.com/AxT-Team/uapi-mcp", + "documentation": "https://uapis.cn/docs", + "license": "MIT" +} diff --git a/package.json b/package.json index 6e1f62c..7c51285 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "uapi-mcp", "version": "0.1.2", "author": "UAPI", - "description": "Uapi Mcp 是 uapis.cn 的官方 MCP Server。", + "description": "Official MCP (Model Context Protocol) server for UAPI / uapis.cn — exposes 100+ public-API endpoints (network, text, image, social, translation, search) as agent tools over Streamable HTTP and stdio. uapis.cn 官方 MCP 服务器。", "type": "module", "sideEffects": false, "engines": { @@ -12,7 +12,7 @@ "type": "git", "url": "git+https://github.com/AxT-Team/uapi-mcp.git" }, - "homepage": "https://github.com/AxT-Team/uapi-mcp#readme", + "homepage": "https://uapis.cn/mcp", "bugs": { "url": "https://github.com/AxT-Team/uapi-mcp/issues" }, @@ -58,5 +58,27 @@ "globals": "^16.0.0", "typescript": "~5.8.3", "typescript-eslint": "^8.31.1" - } + }, + "keywords": [ + "uapi", + "uapis", + "uapis.cn", + "mcp", + "model-context-protocol", + "modelcontextprotocol", + "mcp-server", + "agent", + "agents", + "llm", + "ai", + "claude", + "tools", + "public-api", + "free-api", + "rest-api", + "openapi", + "streamable-http", + "stdio" + ], + "license": "MIT" } diff --git a/smithery.yaml b/smithery.yaml new file mode 100644 index 0000000..8c1078f --- /dev/null +++ b/smithery.yaml @@ -0,0 +1,33 @@ +# Smithery (smithery.ai) deployment manifest for uapi-mcp. +# Reference: https://smithery.ai/docs + +startCommand: + type: stdio + configSchema: + type: object + properties: + uapikey: + type: string + title: UAPI API Key + description: | + Your UAPI key from https://uapis.cn/console. Free-tier endpoints + work without a key, paid endpoints require one. The server forwards + this value as an X-API-Key header on every UAPI request. + required: [] + commandFunction: |- + (config) => ({ + command: "npx", + args: ["-y", "uapi-mcp", "start", "--mode", "dynamic"], + env: { + UAPI_MCP_UAPIKEY: config.uapikey || "" + } + }) + +build: + dockerfile: Dockerfile + +runtime: + protocolVersion: "2025-06-18" + capabilities: + tools: + listChanged: false