justoneapi-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 JustOneAPI MCP Contributors
+
+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,420 @@
+[![npm version](https://badge.fury.io/js/justoneapi-mcp.svg)](https://www.npmjs.com/package/justoneapi-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+[简体中文](README.zh-CN.md) | English
+
+> **Raw JSON by design.** Unmodified upstream responses for maximum data fidelity.
+
+# JustOneAPI MCP Server
+
+Use JustOneAPI inside AI assistants via Model Context Protocol (MCP).
+
+This MCP server is a thin transport layer that exposes JustOneAPI endpoints to AI agents and returns the original raw JSON response from upstream platforms.
+
+---
+
+## What This MCP Does
+
+- Exposes JustOneAPI endpoints as MCP tools
+- Handles authentication, retries, timeouts, and error normalization
+- Returns raw upstream JSON without field parsing
+- Designed for AI agents and developer workflows
+
+---
+
+## What This MCP Does NOT Do
+
+- No field parsing or schema normalization
+- No data restructuring
+- No assumptions about upstream response structure
+
+This design is intentional to preserve data fidelity and long-term compatibility.
+
+---
+
+## Available Tools
+
+This MCP server provides multiple tools to interact with JustOneAPI endpoints. Each tool returns the original raw JSON response from upstream without field parsing.
+
+### Featured Tool: Unified Search
+
+**`unified_search_v1`** - Search across multiple Chinese social media and news platforms in one request.
+
+Supports: Weibo, WeChat, Zhihu, Douyin, Xiaohongshu, Bilibili, Kuaishou, and News.
+
+**How to use (Natural Language):**
+
+Just ask Claude or your MCP host to use the tool with a natural language request:
+- *"Search for AI discussions on Chinese social media from last week"*
+- *"Find posts about deepseek on Weibo from January 1st to 5th"*
+- *"Search for chatgpt OR 机器学习 on all platforms, exclude 广告"*
+
+Claude will automatically:
+- Convert your request to the correct API format
+- Handle date formatting (UTC+8 timezone)
+- Process pagination with nextCursor (just ask "show me more")
+- Return and summarize results
+
+**Search Syntax:**
+- Single keyword: `deepseek`
+- AND search: `deepseek chatgpt` (both must appear)
+- OR search: `deepseek~chatgpt` (either can appear)
+- NOT search: `deepseek -chatgpt` (exclude chatgpt)
+
+**Platform Options:**
+`ALL` (default), `NEWS`, `WEIBO`, `WEIXIN`, `ZHIHU`, `DOUYIN`, `XIAOHONGSHU`, `BILIBILI`, `KUAISHOU`
+
+**Technical Parameters (for reference):**
+```json
+{
+  "keyword": "AI",
+  "source": "ALL",
+  "start": "2025-01-01 00:00:00",
+  "end": "2025-01-02 23:59:59"
+}
+```
+
+### Discovering All Available Tools
+
+To see all available tools in your MCP host (Claude Desktop, Cursor, etc.):
+
+**In Claude Desktop:**
+```
+Please list all available tools from justoneapi-mcp
+```
+
+**In Cursor or other MCP hosts:**
+Use your host's tool discovery feature to see all available tools and their parameters.
+
+Each tool includes:
+- ✅ Complete parameter descriptions
+- ✅ Input validation with Zod schemas
+- ✅ Detailed error messages
+- ✅ Example values in parameter descriptions
+
+### Tool Naming Convention
+
+All tools follow this pattern:
+- `unified_search_v1` - Unified search across platforms
+- `kuaishou_search_video_v2` - Platform-specific video search
+- `{platform}_{action}_{version}` - General pattern
+
+### Complete Tool Documentation
+
+For detailed documentation of all tools, parameters, and examples, see **[TOOLS.md](TOOLS.md)**.
+
+---
+
+## Output Contract
+
+This MCP returns raw JSON from upstream APIs.
+
+Example (simplified):
+
+    {
+      "code": 0,
+      "message": null,
+      "recordTime": "2025-12-31T14:55:21Z",
+      "data": ...
+    }
+
+---
+
+## Authentication
+
+You need a JustOneAPI token to use this server.
+
+**Get your token**: Visit [https://justoneapi.com](https://justoneapi.com) to sign up and obtain your API token.
+
+---
+
+## Installation
+
+### Option 1: npx (Recommended)
+
+Use directly with npx, no installation required.
+
+**Configure Claude Desktop:**
+
+Edit the configuration file for your operating system:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "justoneapi": {
+      "command": "npx",
+      "args": ["-y", "justoneapi-mcp"],
+      "env": {
+        "JUSTONEAPI_TOKEN": "your_actual_token_here"
+      }
+    }
+  }
+}
+```
+
+> 💡 **Get your token**: Sign up at [justoneapi.com](https://justoneapi.com)
+
+### Option 2: Global Installation
+
+```bash
+npm install -g justoneapi-mcp
+```
+
+**Configure Claude Desktop:**
+
+Edit the configuration file for your operating system:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "justoneapi": {
+      "command": "justoneapi-mcp",
+      "env": {
+        "JUSTONEAPI_TOKEN": "your_actual_token_here"
+      }
+    }
+  }
+}
+```
+
+> 💡 **Get your token**: Sign up at [justoneapi.com](https://justoneapi.com)
+
+### Option 3: Local Development
+
+```bash
+git clone <repository>
+cd justoneapi-mcp
+npm install
+npm run build
+```
+
+**Configure Claude Desktop:**
+
+Edit the configuration file for your operating system:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "justoneapi": {
+      "command": "node",
+      "args": ["/absolute/path/to/justoneapi-mcp/dist/index.js"],
+      "env": {
+        "JUSTONEAPI_TOKEN": "your_actual_token_here"
+      }
+    }
+  }
+}
+```
+
+> 💡 **Get your token**: Sign up at [justoneapi.com](https://justoneapi.com)
+
+That's it! Only the token is required.
+
+---
+
+## Usage with Other MCP Hosts
+
+This server follows the standard MCP protocol and is compatible with any MCP host (Cursor, Cline, custom agents, etc.).
+
+Generic configuration:
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "justoneapi-mcp"],
+  "env": {
+    "JUSTONEAPI_TOKEN": "your_actual_token_here"
+  }
+}
+```
+
+Or if globally installed:
+
+```json
+{
+  "command": "justoneapi-mcp",
+  "env": {
+    "JUSTONEAPI_TOKEN": "your_actual_token_here"
+  }
+}
+```
+
+> 💡 **Get your token**: Sign up at [justoneapi.com](https://justoneapi.com)
+
+---
+
+## Quick Start
+
+### 1) Restart Your MCP Host
+
+After configuring, restart Claude Desktop (Cmd + Q) or your MCP host.
+
+### 2) Test the Connection
+
+In Claude Desktop, ask:
+
+```
+Please list all available tools from justoneapi-mcp
+```
+
+You should see the available tools including `unified_search_v1` and `kuaishou_search_video_v2`.
+
+### 3) Use the Unified Search
+
+Try searching across multiple platforms:
+
+```
+Use the unified_search_v1 tool to search for "AI" across all platforms
+from January 1st to January 2nd, 2025.
+```
+
+Claude will automatically format the request and return results from Weibo, WeChat, Zhihu, Douyin, Xiaohongshu, Bilibili, Kuaishou, and News.
+
+**Example conversation:**
+
+**You:** Search for recent discussions about "deepseek" on Chinese social media platforms from the last week.
+
+**Claude:** I'll search for "deepseek" across multiple platforms using the unified search tool.
+
+*[Claude uses unified_search_v1 with appropriate date range and returns aggregated results]*
+
+### 4) Advanced Search Examples
+
+**Platform-specific search:**
+```
+Search for "chatgpt" on Weibo only, from December 1st to January 2nd
+```
+
+**Complex search queries:**
+```
+Search for posts containing "AI" OR "机器学习" but NOT "广告" on Zhihu,
+from the last 30 days
+```
+
+**Pagination (Getting more results):**
+
+When search results have more pages, the response includes a `nextCursor` field. Simply ask Claude to continue:
+
+```
+Show me the next page of results
+```
+or
+```
+Get more results from the previous search
+```
+or
+```
+Continue with the next page
+```
+
+Claude will automatically:
+- Extract the `nextCursor` from the previous response
+- Use it to fetch the next page
+- Continue until no more results are available
+
+**Example conversation with pagination:**
+
+**You:** Search for "AI" on all platforms from January 1-5, 2025
+
+**Claude:** *[Returns first page of results with 10-20 items]*
+
+**You:** Show me more results
+
+**Claude:** *[Uses nextCursor to fetch page 2]*
+
+**You:** Continue
+
+**Claude:** *[Fetches page 3, and so on...]*
+
+💡 **Note**: When using `nextCursor` for pagination, you don't need to provide `start`, `end`, or `source` again - the cursor already contains this information.
+
+---
+
+## Error Handling
+
+All errors are normalized into stable MCP error codes with actionable messages.
+
+### Error Codes
+
+| Error Code | Description | Action                              |
+|------------|-------------|-------------------------------------|
+| `INVALID_TOKEN` | Token is invalid or inactive | Update your `JUSTONEAPI_TOKEN`      |
+| `COLLECT_FAILED` | Data collection failed | Retry after a short delay           |
+| `RATE_LIMITED` | Too many requests | Slow down and retry later           |
+| `DAILY_QUOTA_EXCEEDED` | Daily usage limit reached | Wait until tomorrow or upgrade plan |
+| `INSUFFICIENT_BALANCE` | Account balance too low | Top up your account                 |
+| `PERMISSION_DENIED` | No access to this resource | Contact support                     |
+| `VALIDATION_ERROR` | Invalid request parameters | Check input values                  |
+| `INTERNAL_ERROR` | Server error | Retry later                         |
+| `NETWORK_TIMEOUT` | Request timed out | Check network or retry              |
+| `NETWORK_ERROR` | Network connection failed | Check internet connection           |
+| `UPSTREAM_ERROR` | Unspecified upstream error | Retry or contact support            |
+
+### Error Format
+
+Errors are returned in this format:
+```
+ERROR[ERROR_CODE] (upstream=XXX): Human-readable message
+```
+
+Example:
+```
+ERROR[RATE_LIMITED] (upstream=302): Rate limit exceeded. Please slow down and retry later.
+```
+
+---
+
+## Design Philosophy
+
+Transport, not transformation.
+
+This MCP prioritizes stability, transparency, and raw data fidelity over convenience.
+
+---
+
+## Advanced Configuration (Optional)
+
+By default, the server works with sensible defaults. You only need to set `JUSTONEAPI_TOKEN`.
+
+However, you can customize behavior with these optional environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `JUSTONEAPI_TOKEN` | *(required)* | Your JustOneAPI token |
+| `JUSTONEAPI_BASE_URL` | `https://api.justoneapi.com` | API endpoint |
+| `JUSTONEAPI_TIMEOUT_MS` | `20000` | Request timeout (milliseconds) |
+| `JUSTONEAPI_RETRY` | `1` | Number of retries after first attempt |
+| `JUSTONEAPI_DEBUG` | `false` | Enable debug logging to stderr |
+
+Example with custom settings:
+
+```json
+{
+  "mcpServers": {
+    "justoneapi": {
+      "command": "npx",
+      "args": ["-y", "justoneapi-mcp"],
+      "env": {
+        "JUSTONEAPI_TOKEN": "your_token_here",
+        "JUSTONEAPI_TIMEOUT_MS": "30000",
+        "JUSTONEAPI_DEBUG": "true"
+      }
+    }
+  }
+}
+```
+
+---
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,429 @@
+[![npm version](https://badge.fury.io/js/justoneapi-mcp.svg)](https://www.npmjs.com/package/justoneapi-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+[English](README.md) | 简体中文
+
+> **原始 JSON 设计。** 返回未经修改的上游响应，确保最大数据保真度。
+
+# JustOneAPI MCP 服务器
+
+在 AI 助手中通过模型上下文协议 (MCP) 使用 JustOneAPI。
+
+这是一个轻量级的 MCP 服务器，将 JustOneAPI 接口暴露给 AI 代理，并返回来自上游平台的原始 JSON 响应。
+
+---
+
+## 功能特性
+
+- 将 JustOneAPI 接口暴露为 MCP 工具
+- 处理认证、重试、超时和错误标准化
+- 返回原始的上游 JSON，不解析字段
+- 专为 AI 代理和开发者工作流设计
+
+---
+
+## 不做什么
+
+- 不解析或标准化字段
+- 不重构数据结构
+- 不假设上游响应结构
+
+这样的设计是有意为之，以保持数据保真度和长期兼容性。
+
+---
+
+## 可用工具
+
+本 MCP 服务器提供多个工具来与 JustOneAPI 接口交互。每个工具都返回未经解析的原始上游 JSON 响应。
+
+### 特色工具：统一搜索
+
+**`unified_search_v1`** - 一次请求搜索多个中文社交媒体和新闻平台。
+
+支持平台：微博、微信、知乎、抖音、小红书、哔哩哔哩、快手和新闻。
+
+**使用方法（自然语言）：**
+
+直接用自然语言向 Claude 或你的 MCP 客户端提问：
+- *"搜索最近一周中文社交媒体上关于 AI 的讨论"*
+- *"搜索微博上 1 月 1 日到 5 日关于 deepseek 的帖子"*
+- *"在所有平台搜索 chatgpt 或 机器学习，排除 广告"*
+
+Claude 会自动：
+- 将你的请求转换为正确的 API 格式
+- 处理日期格式化（UTC+8 时区）
+- 使用 nextCursor 处理翻页（只需说"显示更多"）
+- 返回并总结结果
+
+**搜索语法：**
+- 单关键词：`deepseek`
+- AND 搜索：`deepseek chatgpt`（两个词都必须出现）
+- OR 搜索：`deepseek~chatgpt`（任一词出现即可）
+- NOT 搜索：`deepseek -chatgpt`（排除 chatgpt）
+
+**平台选项：**
+`ALL`（默认，全部平台）、`NEWS`（新闻）、`WEIBO`（微博）、`WEIXIN`（微信）、`ZHIHU`（知乎）、`DOUYIN`（抖音）、`XIAOHONGSHU`（小红书）、`BILIBILI`（B站）、`KUAISHOU`（快手）
+
+**技术参数（供参考）：**
+```json
+{
+  "keyword": "AI",
+  "source": "ALL",
+  "start": "2025-01-01 00:00:00",
+  "end": "2025-01-02 23:59:59"
+}
+```
+
+### 发现所有可用工具
+
+在你的 MCP 客户端（Claude Desktop、Cursor 等）中查看所有可用工具：
+
+**在 Claude Desktop 中：**
+```
+请列出 justoneapi-mcp 的所有可用工具
+```
+
+**在 Cursor 或其他 MCP 客户端：**
+使用客户端的工具发现功能查看所有可用工具及其参数。
+
+每个工具都包含：
+- ✅ 完整的参数说明
+- ✅ 使用 Zod 进行输入验证
+- ✅ 详细的错误消息
+- ✅ 参数说明中的示例值
+
+### 工具命名规范
+
+所有工具遵循此模式：
+- `unified_search_v1` - 跨平台统一搜索
+- `kuaishou_search_video_v2` - 平台特定的视频搜索
+- `{平台}_{操作}_{版本}` - 通用模式
+
+### 完整工具文档
+
+详细的工具文档、参数和示例请参见 **[TOOLS.md](TOOLS.md)**。
+
+---
+
+## 输出约定
+
+此 MCP 返回来自上游 API 的原始 JSON。
+
+示例（简化）：
+
+```json
+{
+  "code": 0,
+  "message": null,
+  "recordTime": "2025-12-31T14:55:21Z",
+  "data": ...
+}
+```
+
+---
+
+## 认证
+
+你需要一个 JustOneAPI token 才能使用此服务器。
+
+**获取你的 token**：访问 [https://justoneapi.com](https://justoneapi.com) 注册并获取 API token。
+
+获得 token 后，在 MCP 客户端的环境变量中配置：
+
+```
+JUSTONEAPI_TOKEN=你的实际token
+```
+
+🔒 **安全性**：token 作为查询参数传递给上游 API，绝不会以明文形式记录。所有 URL 在记录前都会脱敏处理。
+
+---
+
+## 安装
+
+### 方式 1：npx（推荐）
+
+直接使用 npx，无需安装。
+
+**配置 Claude Desktop：**
+
+编辑你的操作系统对应的配置文件：
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "justoneapi": {
+      "command": "npx",
+      "args": ["-y", "justoneapi-mcp"],
+      "env": {
+        "JUSTONEAPI_TOKEN": "你的实际token"
+      }
+    }
+  }
+}
+```
+
+> 💡 **获取你的 token**：在 [justoneapi.com](https://justoneapi.com) 注册
+
+### 方式 2：全局安装
+
+```bash
+npm install -g justoneapi-mcp
+```
+
+**配置 Claude Desktop：**
+
+编辑你的操作系统对应的配置文件：
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "justoneapi": {
+      "command": "justoneapi-mcp",
+      "env": {
+        "JUSTONEAPI_TOKEN": "你的实际token"
+      }
+    }
+  }
+}
+```
+
+> 💡 **获取你的 token**：在 [justoneapi.com](https://justoneapi.com) 注册
+
+### 方式 3：本地开发
+
+```bash
+git clone <repository>
+cd justoneapi-mcp
+npm install
+npm run build
+```
+
+**配置 Claude Desktop：**
+
+编辑你的操作系统对应的配置文件：
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "justoneapi": {
+      "command": "node",
+      "args": ["/绝对路径/justoneapi-mcp/dist/index.js"],
+      "env": {
+        "JUSTONEAPI_TOKEN": "你的实际token"
+      }
+    }
+  }
+}
+```
+
+> 💡 **获取你的 token**：在 [justoneapi.com](https://justoneapi.com) 注册
+
+就这么简单！只需要配置 token。
+
+---
+
+## 在其他 MCP 客户端中使用
+
+此服务器遵循标准 MCP 协议，与任何 MCP 客户端兼容（Cursor、Cline、自定义代理等）。
+
+通用配置：
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "justoneapi-mcp"],
+  "env": {
+    "JUSTONEAPI_TOKEN": "你的实际token"
+  }
+}
+```
+
+或如果已全局安装：
+
+```json
+{
+  "command": "justoneapi-mcp",
+  "env": {
+    "JUSTONEAPI_TOKEN": "你的实际token"
+  }
+}
+```
+
+> 💡 **获取你的 token**：在 [justoneapi.com](https://justoneapi.com) 注册
+
+---
+
+## 快速开始
+
+### 1) 重启 MCP 客户端
+
+配置完成后，重启 Claude Desktop（Cmd + Q）或你的 MCP 客户端。
+
+### 2) 测试连接
+
+在 Claude Desktop 中提问：
+
+```
+请列出 justoneapi-mcp 的所有可用工具
+```
+
+你应该能看到可用工具，包括 `unified_search_v1` 和 `kuaishou_search_video_v2`。
+
+### 3) 使用统一搜索
+
+尝试跨平台搜索：
+
+```
+使用 unified_search_v1 工具搜索 2025 年 1 月 1 日到 2 日所有平台上关于 "AI" 的内容
+```
+
+Claude 会自动格式化请求，并返回来自微博、微信、知乎、抖音、小红书、B站、快手和新闻的结果。
+
+**示例对话：**
+
+**你：** 搜索最近一周中文社交媒体平台上关于 "deepseek" 的讨论
+
+**Claude：** 我将使用统一搜索工具搜索 "deepseek"。
+
+*[Claude 使用 unified_search_v1 并适当的日期范围返回聚合结果]*
+
+### 4) 高级搜索示例
+
+**平台特定搜索：**
+```
+搜索 12 月 1 日到 1 月 2 日期间微博上关于 "chatgpt" 的内容
+```
+
+**复杂搜索查询：**
+```
+在知乎搜索包含 "AI" 或 "机器学习" 但不包含 "广告" 的帖子，
+时间范围为最近 30 天
+```
+
+**翻页（获取更多结果）：**
+
+当搜索结果有更多页时，响应中会包含 `nextCursor` 字段。只需让 Claude 继续：
+
+```
+显示下一页结果
+```
+或
+```
+获取更多结果
+```
+或
+```
+继续下一页
+```
+
+Claude 会自动：
+- 从上一个响应中提取 `nextCursor`
+- 使用它获取下一页
+- 持续直到没有更多结果
+
+**翻页对话示例：**
+
+**你：** 搜索 2025 年 1 月 1-5 日所有平台上关于 "AI" 的内容
+
+**Claude：** *[返回第 1 页结果，包含 10-20 条]*
+
+**你：** 显示更多结果
+
+**Claude：** *[使用 nextCursor 获取第 2 页]*
+
+**你：** 继续
+
+**Claude：** *[获取第 3 页，依此类推...]*
+
+💡 **注意**：使用 `nextCursor` 翻页时，不需要再次提供 `start`、`end` 或 `source` - 游标已包含这些信息。
+
+---
+
+## 错误处理
+
+所有错误都标准化为稳定的 MCP 错误代码，并附带可操作的消息。
+
+### 错误代码
+
+| 错误代码 | 说明 | 解决方案 |
+|---------|------|---------|
+| `INVALID_TOKEN` | Token 无效或未激活 | 更新你的 `JUSTONEAPI_TOKEN` |
+| `COLLECT_FAILED` | 数据采集失败 | 稍后重试 |
+| `RATE_LIMITED` | 请求过多 | 降低请求频率，稍后重试 |
+| `DAILY_QUOTA_EXCEEDED` | 达到每日使用限额 | 等到明天或升级套餐 |
+| `INSUFFICIENT_BALANCE` | 账户余额不足 | 充值你的账户 |
+| `PERMISSION_DENIED` | 无权访问此资源 | 验证账户权限 |
+| `VALIDATION_ERROR` | 请求参数无效 | 检查输入值 |
+| `INTERNAL_ERROR` | 服务器错误 | 稍后重试 |
+| `NETWORK_TIMEOUT` | 请求超时 | 检查网络或重试 |
+| `NETWORK_ERROR` | 网络连接失败 | 检查互联网连接 |
+| `UPSTREAM_ERROR` | 未指定的上游错误 | 重试或联系支持 |
+
+### 错误格式
+
+错误以此格式返回：
+```
+ERROR[错误代码] (upstream=XXX): 人类可读的消息
+```
+
+示例：
+```
+ERROR[RATE_LIMITED] (upstream=302): 超出速率限制。请降低速度并稍后重试。
+```
+
+---
+
+## 设计理念
+
+传输，而非转换。
+
+此 MCP 优先考虑稳定性、透明度和原始数据保真度，而非便利性。
+
+---
+
+## 高级配置（可选）
+
+默认情况下，服务器使用合理的默认值。你只需要设置 `JUSTONEAPI_TOKEN`。
+
+但是，你可以使用这些可选环境变量自定义行为：
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `JUSTONEAPI_TOKEN` | *（必需）* | 你的 JustOneAPI token |
+| `JUSTONEAPI_BASE_URL` | `https://api.justoneapi.com` | API 端点 |
+| `JUSTONEAPI_TIMEOUT_MS` | `20000` | 请求超时（毫秒）|
+| `JUSTONEAPI_RETRY` | `1` | 首次尝试后的重试次数 |
+| `JUSTONEAPI_DEBUG` | `false` | 启用调试日志到 stderr |
+
+自定义设置示例：
+
+```json
+{
+  "mcpServers": {
+    "justoneapi": {
+      "command": "npx",
+      "args": ["-y", "justoneapi-mcp"],
+      "env": {
+        "JUSTONEAPI_TOKEN": "你的实际token",
+        "JUSTONEAPI_TIMEOUT_MS": "30000",
+        "JUSTONEAPI_DEBUG": "true"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 许可证
+
+MIT

package/dist/common/config.js

@@ -0,0 +1,44 @@
+import "dotenv/config";
+export const config = {
+    baseUrl: process.env.JUSTONEAPI_BASE_URL ?? "https://api.justoneapi.com",
+    token: process.env.JUSTONEAPI_TOKEN ?? "",
+    // Debug logs go to stderr so Claude Desktop can display them.
+    debug: (process.env.JUSTONEAPI_DEBUG ?? "").toLowerCase() === "true",
+    // Network behavior
+    timeoutMs: Number(process.env.JUSTONEAPI_TIMEOUT_MS ?? "20000"),
+    retry: Number(process.env.JUSTONEAPI_RETRY ?? "1"), // number of retries after the first attempt
+};
+export function requireToken() {
+    if (!config.token || !config.token.trim()) {
+        const err = new Error("Missing JUSTONEAPI_TOKEN. Please set it in the MCP server environment.");
+        err.upstreamCode = 100; // align with your upstream: Invalid token
+        throw err;
+    }
+    return config.token.trim();
+}
+export function maskToken(t) {
+    const s = (t ?? "").trim();
+    if (!s)
+        return "";
+    if (s.length <= 8)
+        return "***";
+    return `${s.slice(0, 3)}***${s.slice(-3)}`;
+}
+/**
+ * Build a "safe" URL for logging:
+ * - keeps path
+ * - masks token query parameter
+ */
+export function toSafeUrlForLog(fullUrl) {
+    try {
+        const u = new URL(fullUrl);
+        if (u.searchParams.has("token")) {
+            u.searchParams.set("token", maskToken(u.searchParams.get("token") ?? ""));
+        }
+        return u.toString();
+    }
+    catch {
+        // Fallback: best-effort masking
+        return fullUrl.replace(/token=([^&]+)/g, (_m, g1) => `token=${maskToken(g1)}`);
+    }
+}

package/dist/common/errors.js

@@ -0,0 +1,86 @@
+export function isUpstreamOk(resp) {
+    return Number(resp?.code) === 0;
+}
+export function mapUpstreamCode(code) {
+    switch (code) {
+        case 100:
+            return "INVALID_TOKEN";
+        case 301:
+            return "COLLECT_FAILED";
+        case 302:
+            return "RATE_LIMITED";
+        case 303:
+            return "DAILY_QUOTA_EXCEEDED";
+        case 400:
+            return "VALIDATION_ERROR";
+        case 500:
+            return "INTERNAL_ERROR";
+        case 600:
+            return "PERMISSION_DENIED";
+        case 601:
+            return "INSUFFICIENT_BALANCE";
+        default:
+            return "UPSTREAM_ERROR";
+    }
+}
+export function buildUserMessage(mcpCode, upstreamMessage) {
+    const base = upstreamMessage && upstreamMessage.trim() ? upstreamMessage.trim() : undefined;
+    switch (mcpCode) {
+        case "INVALID_TOKEN":
+            return base ?? "Invalid or inactive token. Please update JUSTONEAPI_TOKEN.";
+        case "COLLECT_FAILED":
+            return base ?? "Collection failed. Please retry after a short delay.";
+        case "RATE_LIMITED":
+            return base ?? "Rate limit exceeded. Please slow down and retry later.";
+        case "DAILY_QUOTA_EXCEEDED":
+            return base ?? "Daily quota exceeded. Please try again tomorrow or upgrade your plan.";
+        case "VALIDATION_ERROR":
+            return base ?? "Invalid parameters. Please check the input values.";
+        case "PERMISSION_DENIED":
+            return base ?? "Permission denied. Please verify your account permissions.";
+        case "INSUFFICIENT_BALANCE":
+            return base ?? "Insufficient balance. Please top up your account.";
+        case "INTERNAL_ERROR":
+            return base ?? "Internal server error. Please retry later.";
+        case "NETWORK_TIMEOUT":
+            return base ?? "Network timeout. Please retry later.";
+        case "NETWORK_ERROR":
+            return base ?? "Network error. Please retry later.";
+        default:
+            return base ?? "Upstream error. Please retry later.";
+    }
+}
+export function toMcpErrorPayload(e) {
+    const error = e;
+    // Timeout from AbortController
+    if (error.name === "AbortError") {
+        return { code: "NETWORK_TIMEOUT", message: buildUserMessage("NETWORK_TIMEOUT") };
+    }
+    // Our own thrown upstreamCode (business code)
+    if (error.upstreamCode !== undefined) {
+        const upstreamCode = Number(error.upstreamCode);
+        const mcpCode = mapUpstreamCode(upstreamCode);
+        return {
+            code: mcpCode,
+            message: buildUserMessage(mcpCode, error.message),
+            upstreamCode,
+            httpStatus: typeof error.httpStatus === "number" ? error.httpStatus : undefined,
+        };
+    }
+    // HTTP level errors if any
+    if (typeof error.httpStatus === "number") {
+        return {
+            code: "UPSTREAM_ERROR",
+            message: error.message ?? `HTTP error ${error.httpStatus}`,
+            httpStatus: error.httpStatus,
+        };
+    }
+    // Generic network errors
+    if (error.cause || error.code === "ECONNREFUSED" || error.code === "ENOTFOUND") {
+        return {
+            code: "NETWORK_ERROR",
+            message: error.message ?? buildUserMessage("NETWORK_ERROR"),
+        };
+    }
+    return { code: "UPSTREAM_ERROR", message: error.message ?? "Unknown error" };
+}

package/dist/common/http.js

@@ -0,0 +1,82 @@
+import { config, requireToken, toSafeUrlForLog } from "./config.js";
+import { isUpstreamOk } from "./errors.js";
+/**
+ * GET JSON helper for JustOneAPI style responses:
+ * - HTTP may be 200 even when business code != 0
+ * - Throws when:
+ *   - HTTP status not OK
+ *   - JSON parse fails
+ *   - business code != 0
+ * Includes:
+ * - timeout
+ * - small retry
+ * - safe logging (never leaks token)
+ */
+export async function getJson(pathWithQuery) {
+    // ensure token exists early (so we can return INVALID_TOKEN)
+    requireToken();
+    const url = `${config.baseUrl}${pathWithQuery}`;
+    const attempts = 1 + Math.max(0, Number.isFinite(config.retry) ? config.retry : 0);
+    let lastErr;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), config.timeoutMs);
+        try {
+            if (config.debug) {
+                console.error(`[justoneapi] GET ${toSafeUrlForLog(url)} (attempt ${attempt}/${attempts})`);
+            }
+            const res = await fetch(url, { method: "GET", signal: controller.signal });
+            const text = await res.text();
+            let json;
+            try {
+                json = JSON.parse(text);
+            }
+            catch {
+                const err = new Error("Failed to parse JSON response from upstream.");
+                err.httpStatus = res.status;
+                err.payload = text;
+                throw err;
+            }
+            // HTTP-level error
+            if (!res.ok) {
+                const err = new Error(json.message ?? `HTTP ${res.status}`);
+                err.httpStatus = res.status;
+                err.payload = json;
+                // If upstream also provides code, keep it
+                if (json.code !== undefined)
+                    err.upstreamCode = Number(json.code);
+                throw err;
+            }
+            // Business-level error (code != 0)
+            if (!isUpstreamOk(json)) {
+                const err = new Error(json.message ?? `Upstream code ${json.code}`);
+                err.upstreamCode = Number(json.code);
+                err.payload = json;
+                throw err;
+            }
+            return json;
+        }
+        catch (e) {
+            lastErr = e;
+            const error = e;
+            // Retry only for:
+            // - timeout (AbortError)
+            // - HTTP 5xx
+            // - network-type failures
+            const httpStatus = error.httpStatus;
+            const retryable = error.name === "AbortError" ||
+                (typeof httpStatus === "number" && httpStatus >= 500) ||
+                error.code === "ECONNRESET" ||
+                error.code === "ECONNREFUSED" ||
+                error.code === "ENOTFOUND";
+            if (!retryable || attempt === attempts)
+                break;
+            // small backoff
+            await new Promise((r) => setTimeout(r, 250 * attempt));
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    throw lastErr;
+}

package/dist/index.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { toMcpErrorPayload } from "./common/errors.js";
+import { kuaishouSearchVideoV2, KuaishouSearchVideoV2Input, } from "./tools/kuaishou/search_video_v2.js";
+import { unifiedSearchV1, UnifiedSearchV1Input, } from "./tools/search/unified_search_v1.js";
+import { version } from "./version.js";
+const server = new McpServer({
+    name: "justoneapi-mcp",
+    version,
+});
+server.registerTool("kuaishou_search_video_v2", {
+    description: "Search Kuaishou videos by keyword. Returns the original raw JSON response from upstream without field normalization.",
+    inputSchema: KuaishouSearchVideoV2Input.shape,
+}, async (input) => {
+    try {
+        const data = await kuaishouSearchVideoV2(input);
+        return {
+            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        };
+    }
+    catch (e) {
+        const m = toMcpErrorPayload(e);
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: `ERROR[${m.code}] (upstream=${m.upstreamCode ?? "N/A"}): ${m.message}`,
+                },
+            ],
+        };
+    }
+});
+server.registerTool("unified_search_v1", {
+    description: "Unified search across multiple platforms (Weibo, WeChat, Zhihu, Douyin, Xiaohongshu, Bilibili, Kuaishou, News). Search by keyword with time range. Supports AND/OR/NOT operators and pagination. Returns raw JSON response.",
+    inputSchema: UnifiedSearchV1Input.shape,
+}, async (input) => {
+    try {
+        const data = await unifiedSearchV1(input);
+        return {
+            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        };
+    }
+    catch (e) {
+        const m = toMcpErrorPayload(e);
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: `ERROR[${m.code}] (upstream=${m.upstreamCode ?? "N/A"}): ${m.message}`,
+                },
+            ],
+        };
+    }
+});
+async function main() {
+    // Validate configuration on startup
+    if (!process.env.JUSTONEAPI_TOKEN?.trim()) {
+        console.error("[justoneapi-mcp] ERROR: JUSTONEAPI_TOKEN is required but not set.\n" +
+            "Please set the JUSTONEAPI_TOKEN environment variable in your MCP host configuration.");
+        process.exit(1);
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Optional: log startup info to stderr (won't interfere with MCP protocol on stdout)
+    if (process.env.JUSTONEAPI_DEBUG?.toLowerCase() === "true") {
+        console.error(`[justoneapi-mcp] Server started (version ${version})`);
+        console.error(`[justoneapi-mcp] Base URL: ${process.env.JUSTONEAPI_BASE_URL ?? "https://api.justoneapi.com"}`);
+    }
+}
+main().catch((err) => {
+    console.error("[justoneapi-mcp] Fatal error:", err);
+    process.exit(1);
+});

package/dist/tools/kuaishou/search_video_v2.js

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { requireToken } from "../../common/config.js";
+import { getJson } from "../../common/http.js";
+export const KuaishouSearchVideoV2Input = z.object({
+    keyword: z.string().min(1).describe("Search keyword, e.g. 'dance'"),
+    page: z.number().int().min(1).default(1).describe("Page number, default 1"),
+});
+export async function kuaishouSearchVideoV2(input) {
+    const token = encodeURIComponent(requireToken());
+    const keyword = encodeURIComponent(input.keyword);
+    const page = input.page; // zod default ensures it's a number
+    return await getJson(`/api/kuaishou/search-video/v2?token=${token}&keyword=${keyword}&page=${page}`);
+}

package/dist/tools/search/unified_search_v1.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { requireToken } from "../../common/config.js";
+import { getJson } from "../../common/http.js";
+// Platform type enum matching CiviwPlatformType
+export const PlatformType = z.enum([
+    "ALL",
+    "NEWS",
+    "WEIBO",
+    "WEIXIN",
+    "ZHIHU",
+    "DOUYIN",
+    "XIAOHONGSHU",
+    "BILIBILI",
+    "KUAISHOU",
+]);
+export const UnifiedSearchV1Input = z.object({
+    keyword: z
+        .string()
+        .min(1)
+        .describe("Search keyword. Syntax: single keyword 'word', AND 'word1 word2', OR 'word1~word2', NOT 'word -excluded'"),
+    source: PlatformType.optional().describe("Platform source: ALL (default), NEWS, WEIBO, WEIXIN, ZHIHU, DOUYIN, XIAOHONGSHU, BILIBILI, KUAISHOU"),
+    start: z
+        .string()
+        .optional()
+        .describe("Start time in format 'yyyy-MM-dd HH:mm:ss' (UTC+8). Required for first page, must be within 84 days"),
+    end: z
+        .string()
+        .optional()
+        .describe("End time in format 'yyyy-MM-dd HH:mm:ss' (UTC+8). Required for first page, must be after start time"),
+    nextCursor: z
+        .string()
+        .optional()
+        .describe("Pagination cursor from previous response. Use this for subsequent pages instead of start/end times"),
+});
+export async function unifiedSearchV1(input) {
+    const token = encodeURIComponent(requireToken());
+    const keyword = encodeURIComponent(input.keyword);
+    // Build query parameters
+    const params = new URLSearchParams();
+    params.append("token", token);
+    params.append("keyword", keyword);
+    if (input.source) {
+        params.append("source", input.source);
+    }
+    if (input.nextCursor) {
+        // Pagination: use nextCursor
+        params.append("nextCursor", input.nextCursor);
+    }
+    else {
+        // First page: require start and end times
+        if (!input.start || !input.end) {
+            throw new Error("start and end times are required for the first page (unless using nextCursor for pagination)");
+        }
+        params.append("start", input.start);
+        params.append("end", input.end);
+    }
+    return await getJson(`/api/search/v1?${params.toString()}`);
+}

package/dist/tools/unified_search_v1.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { requireToken } from "../common/config.js";
+import { getJson } from "../common/http.js";
+// Platform type enum matching CiviwPlatformType
+export const PlatformType = z.enum([
+    "ALL",
+    "NEWS",
+    "WEIBO",
+    "WEIXIN",
+    "ZHIHU",
+    "DOUYIN",
+    "XIAOHONGSHU",
+    "BILIBILI",
+    "KUAISHOU",
+]);
+export const UnifiedSearchV1Input = z.object({
+    keyword: z
+        .string()
+        .min(1)
+        .describe("Search keyword. Syntax: single keyword 'word', AND 'word1 word2', OR 'word1~word2', NOT 'word -excluded'"),
+    source: PlatformType.optional().describe("Platform source: ALL (default), NEWS, WEIBO, WEIXIN, ZHIHU, DOUYIN, XIAOHONGSHU, BILIBILI, KUAISHOU"),
+    start: z
+        .string()
+        .optional()
+        .describe("Start time in format 'yyyy-MM-dd HH:mm:ss' (UTC+8). Required for first page, must be within 84 days"),
+    end: z
+        .string()
+        .optional()
+        .describe("End time in format 'yyyy-MM-dd HH:mm:ss' (UTC+8). Required for first page, must be after start time"),
+    nextCursor: z
+        .string()
+        .optional()
+        .describe("Pagination cursor from previous response. Use this for subsequent pages instead of start/end times"),
+});
+export async function unifiedSearchV1(input) {
+    const token = encodeURIComponent(requireToken());
+    const keyword = encodeURIComponent(input.keyword);
+    // Build query parameters
+    const params = new URLSearchParams();
+    params.append("token", token);
+    params.append("keyword", keyword);
+    if (input.source) {
+        params.append("source", input.source);
+    }
+    if (input.nextCursor) {
+        // Pagination: use nextCursor
+        params.append("nextCursor", input.nextCursor);
+    }
+    else {
+        // First page: require start and end times
+        if (!input.start || !input.end) {
+            throw new Error("start and end times are required for the first page (unless using nextCursor for pagination)");
+        }
+        params.append("start", input.start);
+        params.append("end", input.end);
+    }
+    return await getJson(`/api/search/v1?${params.toString()}`);
+}

package/dist/version.js

@@ -0,0 +1,15 @@
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+let version = "0.0.0";
+try {
+    const packageJsonPath = join(__dirname, "../package.json");
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    version = packageJson.version || "0.0.0";
+}
+catch (e) {
+    console.error("Failed to read version from package.json:", e);
+}
+export { version };

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "justoneapi-mcp",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "MCP server for JustOneAPI - expose API endpoints to AI assistants via Model Context Protocol",
+  "main": "dist/index.js",
+  "bin": {
+    "justoneapi-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "dev": "node --loader ts-node/esm src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "lint": "eslint src/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "justoneapi",
+    "ai",
+    "agent",
+    "claude",
+    "cursor"
+  ],
+  "author": "Just One API <support@justoneapi.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/justoneapi/justoneapi-mcp.git"
+  },
+  "homepage": "https://github.com/justoneapi/justoneapi-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/justoneapi/justoneapi-mcp/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "dotenv": "^17.2.3",
+    "zod": "^4.3.4"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "@typescript-eslint/eslint-plugin": "^8.51.0",
+    "@typescript-eslint/parser": "^8.51.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.7.4",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}