Related Pages

Related topics: Authentication, MCP Host Integration

Getting Started with JustOneAPI MCP

Overview

JustOneAPI MCP Server is a Model Context Protocol (MCP) server that exposes JustOneAPI endpoints to AI assistants like Claude Desktop, Cursor, and other MCP-compatible hosts. The server acts as a thin transport layer that handles authentication, retries, timeouts, and error normalization while returning raw JSON responses from upstream platforms.

Key Characteristics:

• Returns unmodified upstream JSON responses for maximum data fidelity
• No field parsing or schema normalization
• Designed for AI agents and developer workflows
• Supports multiple Chinese social media and news platforms

Sources: README.md:1-20

Architecture

System Components

graph TD
    A[MCP Host<br/>Claude Desktop/Cursor] --> B[JustOneAPI MCP Server]
    B --> C[JustOneAPI REST API]
    C --> D[Upstream Platforms]
    
    D --> E[Weibo]
    D --> F[WeChat]
    D --> G[Zhihu]
    D --> H[Douyin]
    D --> I[Xiaohongshu]
    D --> J[Bilibili]
    D --> K[Kuaishou]
    D --> L[News]
    
    B --> M[Authentication]
    B --> N[Retry Logic]
    B --> O[Error Normalization]

Technology Stack

Sources: package.json:18-26

Prerequisites

Before using JustOneAPI MCP, ensure you have:

1. Node.js 18.0.0 or higher installed
2. JustOneAPI Token obtained from justoneapi.com
3. MCP-compatible host (Claude Desktop, Cursor, or other)

Installation

Option 1: npx (Recommended)

The simplest method requires no installation. Configure your MCP host to run the package directly via npx.

Sources: README.md:85-95

Option 2: Local Installation

For production environments, install the package locally:

npm install -g justoneapi-mcp

Configuration

Claude Desktop Configuration

Edit the configuration file for your operating system:

Configuration Example:

{
  "mcpServers": {
    "justoneapi": {
      "command": "npx",
      "args": ["-y", "justoneapi-mcp"],
      "env": {
        "JUSTONEAPI_TOKEN": "your_actual_token_here"
      }
    }
  }
}

Sources: README.md:85-102

Environment Variables

Sources: README.md:138-147

Available Tools

Tool Naming Convention

All tools follow the pattern: {platform}_{action}_{version}

Current Tools

Sources: README.md:55-58

Using the Unified Search

Featured Tool: unified_search_v1

Search across multiple Chinese social media and news platforms in a single request.

Supported Platforms:

• Weibo
• WeChat
• Zhihu
• Douyin
• Xiaohongshu
• Bilibili
• Kuaishou
• News (aggregated)

Sources: README.md:36-37

Parameters

Sources: TOOLS.md:21-28

Search Syntax

graph LR
    A[Search Input] --> B{Syntax Type}
    B --> C[Single: deepseek]
    B --> D[AND: deepseek chatgpt]
    B --> E[OR: deepseek~chatgpt]
    B --> F[NOT: deepseek -chatgpt]

Sources: README.md:48-55

Platform Options

Sources: src/tools/search/unified_search_v1.ts:12-19

Usage Examples

Natural Language Queries

Simply ask your MCP host to perform searches:

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 广告

Code-Level Usage

First Page Request:

{
  "keyword": "AI",
  "source": "ALL",
  "start": "2025-01-01 00:00:00",
  "end": "2025-01-02 23:59:59"
}

Pagination Request:

{
  "keyword": "AI",
  "nextCursor": "eyJsYXN0SWQiOiIxMjM0NTY3ODkwIn0="
}

Sources: README.md:40-46

Response Format

All tools return raw JSON from upstream APIs without modification.

Success Response

{
  "code": 0,
  "message": null,
  "recordTime": "2025-12-31T14:55:21Z",
  "data": {
    // Platform-specific data structure
  }
}

Error Response

ERROR[ERROR_CODE] (upstream=XXX): Human-readable message

Sources: README.md:60-75

Error Handling

The MCP normalizes all errors into stable MCP error codes.

Error Codes Reference

Sources: README.md:109-130

Error Format Example

ERROR[RATE_LIMITED] (upstream=302): Rate limit exceeded. Please slow down and retry later.

Sources: README.md:132-134

Pagination

When search results have more pages, responses include a nextCursor field.

How to Paginate

Simply ask for more results:

• "Show me the next page of results"
• "Get more results from the previous search"
• "Continue with the next page"

The MCP host automatically:

1. Extracts the nextCursor from the previous response
2. Uses it to fetch the next page
3. Continues until no more results are available

Note: When using nextCursor for pagination, you don't need to provide start, end, or source again—the cursor already contains this information.

Sources: README.md:76-95

Design Philosophy

Transport, Not Transformation

JustOneAPI MCP prioritizes:

• Stability — Minimal abstraction over upstream APIs
• Transparency — Raw data fidelity without modification
• Compatibility — Long-term compatibility through unchanged responses

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

Sources: README.md:10-24

Advanced Configuration

Complete Configuration Example

{
  "mcpServers": {
    "justoneapi": {
      "command": "npx",
      "args": ["-y", "justoneapi-mcp"],
      "env": {
        "JUSTONEAPI_TOKEN": "your_token_here",
        "JUSTONEAPI_TIMEOUT_MS": "30000",
        "JUSTONEAPI_DEBUG": "true"
      }
    }
  }
}

Retry Behavior

The HTTP client implements automatic retry for:

• Timeout errors (AbortError)
• HTTP 5xx responses
• Network failures (ECONNRESET, ECONNREFUSED, ENOTFOUND)

Sources: src/common/http.ts:30-40

Discovery and Verification

Listing Available Tools

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

Sources: README.md:30-38

Next Steps

After setup:

1. Obtain an API token from justoneapi.com
2. Configure your MCP host with the token
3. Try the unified search with a simple query
4. Explore pagination for large result sets
5. Review error codes for troubleshooting

License

MIT License

Sources: README.md:152

External Resources

• JustOneAPI Dashboard
• JustOneAPI Official Site
• npm Package
• GitHub Repository

Related Pages

Related topics: Getting Started with JustOneAPI MCP, Configuration Reference

Authentication

Overview

The justoneapi-mcp server implements a token-based authentication mechanism for securing API access to the JustOneAPI platform. All requests to upstream APIs are authenticated using a bearer-style token passed via query parameters. The authentication system performs early validation at startup and before each API call to ensure credentials are present and properly configured.

The authentication layer serves as the gatekeeper for all MCP tools, including unified_search_v1 and kuaishou_search_video_v2. It validates the token's presence, encodes it safely for transmission, and provides clear error messages when authentication fails.

Architecture

graph TD
    A[MCP Host Request] --> B{Token Present?}
    B -->|No| C[Startup Validation<br/>src/index.ts:45-52]
    B -->|Yes| D[requireToken Call]
    
    D --> E{Token Valid?}
    E -->|Empty/Whitespace| F[INVALID_TOKEN Error]
    E -->|Valid| G[Encode Token]
    
    G --> H[Append to Query Params]
    H --> I[HTTP Request via getJson]
    
    I --> J{Response Code = 0?}
    J -->|Yes| K[Return Data]
    J -->|No| L[Error Mapping<br/>src/common/errors.ts]
    
    style F fill:#ffcccc
    style K fill:#ccffcc

Configuration

Environment Variables

Authentication is configured through environment variables in the MCP server configuration.

Token Configuration File

The token configuration is managed in src/common/config.ts.

// src/common/config.ts:1-15
export function requireToken(): string {
  const token = process.env.JUSTONEAPI_TOKEN;
  if (!token || !token.trim()) {
    throw new Error(
      "JUSTONEAPI_TOKEN environment variable is required. " +
        "Get your token at https://justoneapi.com"
    );
  }
  return token;
}

The requireToken() function validates that the token exists and is not empty or whitespace-only. If validation fails, it throws an error with instructions for obtaining a token. Sources: src/common/config.ts:1-15

Startup Validation

The server performs authentication validation during startup to fail fast if credentials are missing.

// src/index.ts:45-52
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);
  }
  // ... continue with server initialization
}

Sources: src/index.ts:45-52

Token Transmission

Query Parameter Encoding

Tokens are transmitted via URL query parameters for all API requests. The token is URL-encoded to handle special characters safely.

// src/tools/search/unified_search_v1.ts:35-36
export async function unifiedSearchV1(input: z.infer<typeof UnifiedSearchV1Input>) {
  const token = encodeURIComponent(requireToken());
  const keyword = encodeURIComponent(input.keyword);
  
  // Build query parameters
  const params = new URLSearchParams();
  params.append("token", token);
  params.append("keyword", keyword);
  // ...
}

Sources: src/tools/search/unified_search_v1.ts:35-36

HTTP Request Flow

All authenticated requests flow through the getJson() helper in src/common/http.ts.

sequenceDiagram
    participant MCP as MCP Host
    participant Server as justoneapi-mcp
    participant API as JustOneAPI
    
    MCP->>Server: Tool Request
    Server->>Server: requireToken()
    Note over Server: Validate token exists
    Server->>Server: getJson(pathWithQuery)
    Server->>API: GET with token in query
    API-->>Server: JSON Response
    Server->>Server: Check response.code
    alt code != 0
        Server->>Server: toMcpErrorPayload()
    end
    Server-->>MCP: Result or Error

The getJson() function includes the following security and reliability features:

// src/common/http.ts:40-55
export async function getJson(pathWithQuery: string): Promise<UpstreamResponse> {
  // 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: ApiError | unknown;

  for (let attempt = 1; attempt <= attempts; attempt++) {
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), config.timeoutMs);
    // ...
  }
}

Sources: src/common/http.ts:40-55

Error Handling

Token-Related Error Codes

When authentication fails, the server returns normalized MCP error codes.

Error Mapping

The mapUpstreamCode() function in src/common/errors.ts maps upstream error codes to MCP error codes.

// src/common/errors.ts:1-30
function mapUpstreamCode(code: number): JOAErrorCode {
  switch (code) {
    case 10001:
      return "INVALID_TOKEN";
    case 10002:
      return "INSUFFICIENT_BALANCE";
    case 10003:
      return "PERMISSION_DENIED";
    // ... other mappings
    default:
      return "UPSTREAM_ERROR";
  }
}

Sources: src/common/errors.ts:1-30

Error Payload Construction

// src/common/errors.ts:60-75
export function toMcpErrorPayload(e: unknown): {
  code: JOAErrorCode;
  message: string;
  upstreamCode?: number;
  httpStatus?: number;
} {
  const error = e as {
    name?: string;
    message?: string;
    upstreamCode?: number;
    httpStatus?: number;
    code?: string;
    cause?: unknown;
  };
  
  // 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,
    };
  }
  // ...
}

Sources: src/common/errors.ts:60-75

Error Response Format

All errors are returned in a standardized format:

ERROR[ERROR_CODE] (upstream=XXX): Human-readable message

Example error responses:

Security Considerations

Token Masking in Logs

Debug logging masks tokens to prevent accidental exposure.

// src/common/config.ts:50-65
export function toSafeUrlForLog(fullUrl: string): string {
  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)}`);
  }
}

Sources: src/common/config.ts:50-65

Retry Behavior with Tokens

Retry logic applies only to transient failures, not authentication errors:

// src/common/http.ts:70-80
const retryable =
  error.name === "AbortError" ||
  (typeof httpStatus === "number" && httpStatus >= 500) ||
  error.code === "ECONNRESET" ||
  error.code === "ECONNREFUSED" ||
  error.code === "ENOTFOUND";

Configuration Examples

Claude Desktop Configuration

{
  "mcpServers": {
    "justoneapi": {
      "command": "npx",
      "args": ["-y", "justoneapi-mcp"],
      "env": {
        "JUSTONEAPI_TOKEN": "your_actual_token_here"
      }
    }
  }
}

Custom Timeout and Debug Settings

{
  "mcpServers": {
    "justoneapi": {
      "command": "npx",
      "args": ["-y", "justoneapi-mcp"],
      "env": {
        "JUSTONEAPI_TOKEN": "your_actual_token_here",
        "JUSTONEAPI_TIMEOUT_MS": "30000",
        "JUSTONEAPI_DEBUG": "true"
      }
    }
  }
}

When debug mode is enabled, logs appear with masked tokens:

[justoneapi] GET https://api.justoneapi.com/api/search/v1?token=sk_***&keyword=AI (attempt 1/2)

Obtaining a Token

1. Visit https://justoneapi.com
2. Create an account or sign in at https://dashboard.justoneapi.com
3. Generate an API token from your dashboard
4. Configure the token in your MCP host

Related Documentation

• README.md — Installation and quick start guide
• TOOLS.md — Complete tool reference with authentication parameters

Related Pages

Related topics: HTTP Client Implementation, Unified Search Tool, Kuaishou Video Search Tool

System Architecture

Overview

The justoneapi-mcp is a Model Context Protocol (MCP) server that provides a bridge between AI assistants and the JustOneAPI social media search platform. The system enables natural language querying across multiple Chinese social media platforms including Weibo, WeChat, Zhihu, Douyin, Xiaohongshu, Bilibili, Kuaishou, and news sources.

The architecture follows a transport-oriented design philosophy, prioritizing stability, transparency, and raw data fidelity over convenience. The MCP server returns unmodified upstream API responses to ensure maximum data fidelity and long-term compatibility.

High-Level Architecture

graph TD
    subgraph "MCP Host Environment"
        A[MCP Client<br/>Claude Desktop/Cursor]
    end
    
    subgraph "justoneapi-mcp Server"
        B[MCP SDK Server]
        C[Tool Handlers]
        D[Common Libraries]
        E[HTTP Client]
    end
    
    subgraph "External Services"
        F[JustOneAPI<br/>api.justoneapi.com]
        G[Chinese Social Media<br/>Platforms]
    end
    
    A -->|MCP Protocol| B
    B --> C
    C --> D
    D --> E
    E -->|HTTPS| F
    F -->|API Responses| G
    
    style A fill:#e1f5fe
    style F fill:#fff3e0
    style G fill:#f3e5f5

Core Components

Component Overview

Module Dependency Graph

graph LR
    subgraph "Entry Point"
        A[src/index.ts]
    end
    
    subgraph "Tool Layer"
        B[unified_search_v1.ts]
        C[kuaishou_search_video_v2.ts]
    end
    
    subgraph "Common Layer"
        D[config.ts]
        E[http.ts]
        F[errors.ts]
    end
    
    subgraph "External"
        G[JustOneAPI]
    end
    
    A --> B
    A --> C
    B --> D
    B --> E
    B --> F
    C --> D
    C --> E
    C --> F
    E --> F
    E --> G
    
    style A fill:#ffecb3
    style D fill:#c8e6c9
    style E fill:#c8e6c9
    style F fill:#c8e6c9
    style G fill:#fff3e0

Tool Registration System

Request Flow

sequenceDiagram
    participant Client as MCP Client
    participant Server as MCP Server
    participant Handler as Tool Handler
    participant HTTP as HTTP Client
    participant API as JustOneAPI
    
    Client->>Server: Tool Request (unified_search_v1)
    Server->>Handler: Forward Input
    Handler->>Handler: Validate with Zod Schema
    Handler->>HTTP: GET /api/search/v1
    HTTP->>HTTP: Token encoding
    HTTP->>API: Request with token
    API-->>HTTP: JSON Response
    HTTP-->>Handler: Raw JSON
    Handler-->>Server: JSON Response
    Server-->>Client: MCP Response

Tool Registration Pattern

Tools are registered in src/index.ts using the MCP SDK's registerTool method. Each tool registration includes:

1. Tool name - Unique identifier following {platform}_{action}_{version} pattern
2. Input schema - Zod schema for parameter validation
3. Handler function - Async function that processes requests

// Registration pattern from src/index.ts:55-72
server.registerTool(
  "unified_search_v1",
  {
    description: "Unified search across multiple platforms...",
    inputSchema: UnifiedSearchV1Input.shape,
  },
  async (input) => {
    try {
      const data = await unifiedSearchV1(input);
      return {
        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
      };
    } catch (e: unknown) {
      const m = toMcpErrorPayload(e);
      return {
        isError: true,
        content: [{ type: "text", text: `ERROR[${m.code}]: ${m.message}` }],
      };
    }
  }
);

HTTP Client Architecture

Retry Strategy

The HTTP client in src/common/http.ts implements an intelligent retry mechanism with exponential backoff.

graph TD
    A[Request] --> B{Attempt < Max?}
    B -->|Yes| C{Check Retryable?}
    C -->|AbortError| D[Retry]
    C -->|HTTP 5xx| D
    C -->|ECONNRESET| D
    C -->|ECONNREFUSED| D
    C -->|ENOTFOUND| D
    C -->|No| E[Throw Error]
    D --> F[Wait 250ms × Attempt]
    F --> G[Retry Request]
    G --> B
    B -->|No| H[Throw Last Error]
    
    style E fill:#ffcdd2
    style H fill:#ffcdd2
    style D fill:#c8e6c9

Retryable Conditions

Sources: src/common/http.ts:29-36

Error Handling System

Error Flow

graph TD
    A[Exception Thrown] --> B{Error Type?}
    B -->|AbortError| C[NETWORK_TIMEOUT]
    B -->|upstreamCode exists| D[Map Upstream Code]
    B -->|httpStatus exists| E[UPSTREAM_ERROR]
    B -->|cause or network code| F[NETWORK_ERROR]
    B -->|Unknown| G[UPSTREAM_ERROR]
    
    D --> H[Return MCP Error Payload]
    C --> H
    E --> H
    F --> H
    G --> H
    
    style C fill:#fff9c4
    style D fill:#fff9c4
    style E fill:#fff9c4
    style F fill:#fff9c4

Error Code Mapping

Configuration Management

Environment Variables

Token Management

The requireToken() function in src/common/config.ts validates and retrieves the API token:

export function requireToken(): string {
  const token = process.env.JUSTONEAPI_TOKEN?.trim();
  if (!token) {
    throw new Error("JUSTONEAPI_TOKEN environment variable is required");
  }
  return token;
}

URL Sanitization for Logging

The toSafeUrlForLog() function masks sensitive tokens in URLs before logging:

graph LR
    A[Full URL with token] --> B[Parse URL]
    B --> C{Token param exists?}
    C -->|Yes| D[Mask token value]
    C -->|No| E[Return original]
    D --> F[Return sanitized URL]
    E --> F

Tool Specifications

Available Tools

Platform Support

The unified search supports the following platforms:

Search Syntax Support

Data Flow Architecture

Unified Search Flow

sequenceDiagram
    participant User
    participant Handler as unified_search_v1
    participant HTTP as getJson
    participant API as JustOneAPI
    
    User->>Handler: {keyword, source, start, end}
    Handler->>Handler: Encode parameters
    Handler->>HTTP: GET /api/search/v1?token=...&keyword=...
    HTTP->>API: HTTPS Request
    API-->>HTTP: {code, message, data, nextCursor}
    HTTP-->>Handler: Raw JSON response
    Handler-->>User: JSON with raw data
    
    Note over User,API: Raw upstream data returned unchanged

Technology Stack

Production Dependencies

Development Dependencies

Node.js Requirement

• Minimum version: Node.js 18.0.0
• Runtime: ES2022+ module system

Startup and Initialization

Configuration Validation

On server startup, the main function validates that required configuration exists:

graph TD
    A[Server Start] --> B{JUSTONEAPI_TOKEN set?}
    B -->|No| C[Exit with Error]
    B -->|Yes| D[Start MCP Server]
    D --> E[Register Tools]
    E --> F[Listen for Requests]
    
    style C fill:#ffcdd2
    style F fill:#c8e6c9

The token validation occurs in src/index.ts before the MCP server begins accepting connections, ensuring early failure with clear error messages.

Design Philosophy

The architecture embodies the "Transport, not transformation" principle:

1. Maximum Data Fidelity - Raw upstream responses are returned unmodified
2. No Field Parsing - Data structures remain as received from upstream APIs
3. No Data Restructuring - No normalization or transformation of response formats
4. Long-term Compatibility - Stable interface despite upstream API changes

Related Pages

Related topics: System Architecture, Error Handling, Configuration Reference

HTTP Client Implementation

Overview

The HTTP Client Implementation provides a centralized, reusable HTTP communication layer for the JustOneAPI MCP server. It handles all outbound API requests with built-in retry logic, timeout management, error normalization, and secure logging. The implementation follows a "transport, not transformation" philosophy, returning raw upstream responses to maintain maximum data fidelity.

Key Responsibilities:

• Execute HTTP GET requests to the JustOneAPI backend
• Manage request timeouts using AbortController
• Implement automatic retry with exponential backoff for transient failures
• Normalize errors into structured MCP error codes
• Ensure secure logging by masking sensitive tokens

Sources: src/common/http.ts:48-68

Architecture

graph TD
    A[Tool Handler] --> B[API Function<br/>e.g., unifiedSearchV1]
    B --> C[getJson]
    C --> D{Token Validation}
    D -->|Invalid| E[INVALID_TOKEN Error]
    D -->|Valid| F[Build URL]
    F --> G[Fetch with Timeout]
    G --> H{Response OK?}
    H -->|No| I[Retry Logic]
    I --> G
    H -->|Yes| J[Parse JSON]
    J --> K[Business Code OK?]
    K -->|No| L[Error Mapping]
    K -->|Yes| M[Return Response]
    L --> N[MCP Error Payload]
    
    style E fill:#ff6b6b
    style N fill:#ffa500
    style M fill:#51cf66

Request Flow

1. Token Validation - Ensures JUSTONEAPI_TOKEN exists before making requests Sources: src/common/http.ts:60 src/common/config.ts

1. URL Construction - Builds full URL with base URL and query parameters Sources: src/common/http.ts:62

1. Fetch Execution - Makes HTTP request with AbortController timeout Sources: src/common/http.ts:70-76

1. Response Processing - Validates HTTP status and parses JSON Sources: src/common/http.ts:78-88

1. Business Logic Check - Validates upstream code === 0 for success Sources: src/common/errors.ts:1-18

Core Components

ApiError Type

The ApiError interface extends the standard Error type with additional properties for HTTP-level and business-level error information.

Sources: src/common/http.ts:39-45

getJson Function

The main HTTP client function that performs GET requests with comprehensive error handling.

export async function getJson(pathWithQuery: string): Promise<UpstreamResponse>

Parameters:

Returns: Promise<UpstreamResponse> - Parsed JSON response from the API

Behavior:

• Validates token presence before any network call
• Supports configurable retry attempts (default: 1 retry after initial attempt)
• Implements 250ms backoff between retries
• Returns raw upstream JSON without transformation

Sources: src/common/http.ts:48-68

Retry Logic

The HTTP client implements intelligent retry behavior for transient failures.

Retry Conditions

graph LR
    A[Request Attempt] --> B{Error Type?}
    B -->|AbortError| C[Retry]
    B -->|5xx| C
    B -->|Network Error| C
    B -->|4xx| D[No Retry]
    B -->|Business Error| D
    C --> E{Attempts<br/>Exhausted?}
    E -->|No| A
    E -->|Yes| F[Throw Error]
    D --> F

Retry Configuration:

• Maximum attempts: 1 + JUSTONEAPI_RETRY (default: 2 total attempts)
• Backoff delay: 250ms * attempt_number

Sources: src/common/http.ts:68-96

Timeout Management

Timeouts are implemented using the AbortController API for native browser/Node.js compatibility.

Implementation:

const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), config.timeoutMs);

const res = await fetch(url, { method: "GET", signal: controller.signal });
// ... process response ...
clearTimeout(timer); // Clean up timer

When a timeout occurs, an AbortError is thrown, which triggers the retry logic.

Sources: src/common/http.ts:70-76

Error Handling

Error Code Mapping

The system maps upstream error codes to standardized MCP error codes.

Sources: src/common/errors.ts:19-53

Error Payload Structure

When an error occurs, the toMcpErrorPayload function converts the error to a structured format.

{
  code: JOAErrorCode;      // Normalized MCP error code
  message: string;         // Human-readable message
  upstreamCode?: number;  // Original upstream error code
  httpStatus?: number;     // HTTP status code
}

Error Priority:

1. AbortError → NETWORK_TIMEOUT
2. upstreamCode present → Maps to appropriate MCP code
3. httpStatus present → UPSTREAM_ERROR
4. cause or network error code → NETWORK_ERROR
5. Fallback → UPSTREAM_ERROR

Sources: src/common/errors.ts:55-91

Security Features

Token Masking

All API tokens are masked in logs to prevent credential leakage.

export function toSafeUrlForLog(fullUrl: string): string {
  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)}`);
  }
}

Features:

• Primary method uses URL API for accurate parsing
• Fallback regex for non-standard URLs
• Two-level fallback to prevent logging failures

Sources: src/common/config.ts:58-74

Debug Logging

When JUSTONEAPI_DEBUG=true, requests are logged to stderr with masked tokens:

[justoneapi] GET https://api.justoneapi.com/api/search/v1?token=***&keyword=AI (attempt 1/2)

Sources: src/common/http.ts:72-74

Configuration

Environment Variables

Sources: README.md:103-110

Usage Examples

Basic Tool Implementation

Tools in this MCP server use the HTTP client through dedicated API functions:

// From unified_search_v1.ts
export async function unifiedSearchV1(input: z.infer<typeof UnifiedSearchV1Input>) {
  const token = encodeURIComponent(requireToken());
  const keyword = encodeURIComponent(input.keyword);

  const params = new URLSearchParams();
  params.append("token", token);
  params.append("keyword", keyword);

  if (input.source) {
    params.append("source", input.source);
  }

  if (input.nextCursor) {
    params.append("nextCursor", input.nextCursor);
  } else {
    params.append("start", input.start);
    params.append("end", input.end);
  }

  return await getJson(`/api/search/v1?${params.toString()}`);
}

Sources: src/tools/search/unified_search_v1.ts:29-54

Error Response Format

All errors are returned in a consistent MCP format:

ERROR[ERROR_CODE] (upstream=XXX): Human-readable message

Example:

ERROR[RATE_LIMITED] (upstream=302): Rate limit exceeded. Please slow down and retry later.

Sources: README.md:86-89

Integration with MCP Server

The HTTP client is integrated into the MCP server's tool registration system:

server.registerTool(
  "unified_search_v1",
  {
    description: "Unified search across multiple platforms...",
    inputSchema: UnifiedSearchV1Input.shape,
  },
  async (input) => {
    try {
      const data = await unifiedSearchV1(input);
      return {
        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
      };
    } catch (e: unknown) {
      const m = toMcpErrorPayload(e);
      return {
        isError: true,
        content: [
          {
            type: "text",
            text: `ERROR[${m.code}] (upstream=${m.upstreamCode ?? "N/A"}): ${m.message}`,
          },
        ],
      };
    }
  }
);

Sources: src/index.ts:50-70

Dependencies

The HTTP client implementation uses the following dependencies:

Sources: package.json:16-23

Related Pages

Related topics: Kuaishou Video Search Tool, Tool Naming Conventions and Standards, Error Handling

Unified Search Tool

Overview

The Unified Search Tool (unified_search_v1) is the primary MCP (Model Context Protocol) tool provided by justoneapi-mcp. It enables aggregated searching across multiple Chinese social media platforms and news sources through a single API interface.

Key Characteristics:

• Searches 8 platforms simultaneously in one request
• Returns raw, unmodified JSON from upstream APIs
• Supports advanced search syntax (AND, OR, NOT operators)
• Implements cursor-based pagination
• UTC+8 timezone for all date/time operations

Sources: TOOLS.md:43-60

Architecture

System Context

graph TD
    subgraph "MCP Host"
        A[Claude / Cursor]
    end
    
    subgraph "justoneapi-mcp"
        B[Server Entry<br/>src/index.ts]
        C[Tool Handler<br/>unified_search_v1]
        D[HTTP Client<br/>src/common/http.ts]
        E[Error Handler<br/>src/common/errors.ts]
    end
    
    subgraph "External"
        F[JustOneAPI<br/>api.justoneapi.com]
    end
    
    A -->|MCP Protocol| B
    B --> C
    C --> D
    D -->|GET /api/search/v1| F
    F -->|JSON Response| D
    D --> E
    
    style F fill:#f9f,stroke:#333
    style D fill:#bbf,stroke:#333
    style E fill:#fbb,stroke:#333

Request Flow

sequenceDiagram
    participant MCP as MCP Host
    participant Server as justoneapi-mcp
    participant HTTP as HTTP Client
    participant API as JustOneAPI
    
    MCP->>Server: unified_search_v1(params)
    Server->>HTTP: getJson(endpoint, params)
    
    loop Retry Logic (max 2 attempts)
        HTTP->>API: GET /api/search/v1
        API-->>HTTP: JSON Response
        
        alt Success (code=0)
            HTTP-->>Server: data
        else Retryable Error (5xx, timeout)
            HTTP->>HTTP: Wait 250ms * attempt
        end
    end
    
    alt Non-retryable Error
        Server->>Server: toMcpErrorPayload(e)
        Server-->>MCP: ERROR[...]
    else Success
        Server-->>MCP: Raw JSON response
    end

Sources: src/index.ts:29-47 Sources: src/common/http.ts:1-44

Parameters

Note: start and end are required for the first page request. They must be omitted when using nextCursor for pagination.

Sources: src/tools/search/unified_search_v1.ts:16-41

Supported Platforms

Sources: src/tools/search/unified_search_v1.ts:9-16

Search Syntax

The unified search supports advanced query operators:

Syntax Rules:

• Single keyword: Plain text match
• AND operator: Space-separated terms (implicit)
• OR operator: Tilde (~) separator
• NOT operator: Dash (-) prefix on exclusion term

Sources: TOOLS.md:62-69

Pagination

Cursor-Based Pagination

graph LR
    A[First Request<br/>start, end] --> B[Response<br/>data + nextCursor]
    B --> C{Next Page?}
    C -->|Yes| D[Next Request<br/>nextCursor]
    D --> E[Response<br/>data + nextCursor]
    E --> C
    C -->|No| F[Done]

Pagination Rules

1. First Request: Include start and end time parameters
2. Subsequent Requests: Use nextCursor instead of time parameters
3. Final Page: Response without nextCursor indicates completion

When nextCursor is provided, start, end, and source parameters should be omitted—the cursor contains all necessary pagination context.

Sources: TOOLS.md:32-42

Response Format

Success Response

{
  "code": 0,
  "message": null,
  "recordTime": "2025-01-02T14:55:21Z",
  "data": {
    // Platform-specific data structure
  }
}

Error Response

ERROR[ERROR_CODE] (upstream=XXX): Human-readable message

Sources: src/common/errors.ts:1-72

Configuration

Environment Variables

MCP Server Configuration

{
  "mcpServers": {
    "justoneapi": {
      "command": "npx",
      "args": ["-y", "justoneapi-mcp"],
      "env": {
        "JUSTONEAPI_TOKEN": "your_token_here"
      }
    }
  }
}

Usage Examples

Basic Multi-Platform Search

Search for "AI" discussions on all platforms from January 1-5, 2025

Generated Parameters:

{
  "keyword": "AI",
  "source": "ALL",
  "start": "2025-01-01 00:00:00",
  "end": "2025-01-05 23:59:59"
}

Platform-Specific Search

Search for "chatgpt" on Weibo only, from December 1st to January 2nd

Generated Parameters:

{
  "keyword": "chatgpt",
  "source": "WEIBO",
  "start": "2024-12-01 00:00:00",
  "end": "2025-01-02 23:59:59"
}

Complex Query with OR and NOT

Search for posts containing "deepseek" OR "机器学习" but NOT "广告"

Generated Parameters:

{
  "keyword": "deepseek~机器学习 -广告",
  "source": "ZHIHU",
  "start": "2025-01-01 00:00:00",
  "end": "2025-01-31 23:59:59"
}

Pagination Request

When continuing from a previous response:

{
  "keyword": "AI",
  "nextCursor": "eyJsYXN0SWQiOiIxMjM0NTY3ODkwIn0="
}

Sources: README.md:1-80

Design Philosophy

The Unified Search Tool follows the "Transport, not transformation" principle:

• Maximum data fidelity: Returns unmodified upstream JSON responses
• No field parsing: Raw response structure preserved
• No data restructuring: Original field names and hierarchy maintained
• Long-term compatibility: Interface stability prioritized over convenience

This approach ensures that clients receive complete, unmodified data for any downstream processing needs.

Sources: README.md:95-105

Implementation

Error with Openai API: output new_sensitive (1027)

Please check that you have set the OPENAI_API_KEY environment variable with a valid API key.

Related Pages

Related topics: Unified Search Tool, Tool Naming Conventions and Standards

Kuaishou Video Search Tool

Overview

The Kuaishou Video Search Tool (kuaishou_search_video_v2) is a Model Context Protocol (MCP) tool that enables users to search for videos on Kuaishou, a major Chinese short-video platform. It integrates with the JustOneAPI service to provide programmatic access to Kuaishou's video search functionality.

Key Characteristics:

• Platform-specific search targeting Kuaishou exclusively
• Pagination support for result browsing
• Returns raw, untransformed JSON responses from the upstream API
• Zod-based input validation with clear parameter descriptions

Sources: src/tools/kuaishou/search_video_v2.ts:1-16

Architecture

System Context

The tool operates within the broader justoneapi-mcp server architecture, which uses the MCP SDK to expose tools to AI hosts like Claude Desktop or Cursor.

graph TD
    A[MCP Host<br/>Claude Desktop/Cursor] -->|registerTool| B[justoneapi-mcp Server]
    B -->|registerTool| C[kuaishou_search_video_v2]
    C -->|requireToken| D[Config Module]
    C -->|HTTP GET| E[JustOneAPI Gateway]
    E -->|Proxies to| F[Kuaishou API]
    F -->|JSON Response| E
    E -->|Raw JSON| C
    C -->|Formatted Result| B
    B -->|MCP Response| A

Component Responsibilities

Sources: src/index.ts:18-37

Input Parameters

The KuaishouSearchVideoV2Input schema defines the tool's input contract using Zod validation.

Parameter Specification

Zod Schema Definition

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"),
});

Validation Rules:

• keyword must be a non-empty string (minimum 1 character)
• page must be a positive integer; defaults to 1 if not provided

Sources: src/tools/kuaishou/search_video_v2.ts:4-8

API Request Flow

Request Construction

The tool builds the API request by encoding parameters and appending them to the endpoint URL:

export async function kuaishouSearchVideoV2(input: z.infer<typeof KuaishouSearchVideoV2Input>) {
  const token = encodeURIComponent(requireToken());
  const keyword = encodeURIComponent(input.keyword);
  const page = input.page;

  return await getJson(
    `/api/kuaishou/search-video/v2?token=${token}&keyword=${keyword}&page=${page}`
  );
}

Request Flow Diagram

sequenceDiagram
    participant Client as MCP Tool Handler
    participant Config as Config Module
    participant HTTP as HTTP Client
    participant API as JustOneAPI Gateway

    Client->>Config: requireToken()
    Config-->>Client: Returns JUSTONEAPI_TOKEN
    
    Client->>Client: encodeURIComponent(token, keyword, page)
    
    Client->>HTTP: getJson(/api/kuaishou/search-video/v2?...)
    HTTP->>API: GET Request
    
    alt Success (2xx)
        API-->>HTTP: { code: 0, data: {...} }
        HTTP-->>Client: Parsed JSON object
    else Error (4xx/5xx)
        API-->>HTTP: Error response
        HTTP-->>Client: Throws ApiError
    end

Sources: src/tools/kuaishou/search_video_v2.ts:10-16

Error Handling

All errors are normalized into MCP error codes with actionable messages.

Error Code Reference

Error Response Format

Errors are returned in a standardized format:

ERROR[ERROR_CODE] (upstream=XXX): Human-readable message

Example:

ERROR[RATE_LIMITED] (upstream=302): Rate limit exceeded. Please slow down and retry later.

Sources: README.md:78-95

Error Processing in MCP Handler

async (input) => {
  try {
    const data = await kuaishouSearchVideoV2(input);
    return {
      content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
    };
  } catch (e: unknown) {
    const m = toMcpErrorPayload(e);
    return {
      isError: true,
      content: [{
        type: "text",
        text: `ERROR[${m.code}] (upstream=${m.upstreamCode ?? "N/A"}): ${m.message}`,
      }],
    };
  }
}

Sources: src/index.ts:20-36

HTTP Retry Mechanism

The underlying HTTP client implements automatic retry logic for transient failures.

Retry Conditions

Retry Strategy

• Attempts: Configurable via JUSTONEAPI_RETRY (default: 1 retry after first attempt)
• Backoff: 250ms × attempt number between retries
• Timeout: Configurable via JUSTONEAPI_TIMEOUT_MS (default: 20000ms)

graph TD
    A[HTTP Request] --> B{Success?}
    B -->|Yes| C[Return JSON]
    B -->|No| D{Retryable Error?}
    D -->|No| E[Throw Error]
    D -->|Yes| F{Attempts Remaining?}
    F -->|No| E
    F -->|Yes| G[Wait 250ms × attempt]
    G --> A

Sources: src/common/http.ts:32-42

Tool Registration

The tool is registered with the MCP server using the SDK's registerTool method.

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) => {
    // Implementation...
  }
);

Registration Details:

• Tool Name: kuaishou_search_video_v2
• Schema: KuaishouSearchVideoV2Input.shape (Zod-derived)
• Response Type: Raw JSON text with indentation

Sources: src/index.ts:18-37

Configuration

Environment Variables

Token Security

The configuration module masks tokens in log output for security:

export function toSafeUrlForLog(fullUrl: string): string {
  try {
    const u = new URL(fullUrl);
    if (u.searchParams.has("token")) {
      u.searchParams.set("token", maskToken(u.searchParams.get("token") ?? ""));
    }
    return u.toString();
  } catch {
    return fullUrl.replace(/token=([^&]+)/g, (_m, g1) => `token=${maskToken(g1)}`);
  }
}

Sources: src/common/config.ts:27-41

Response Contract

Success Response Format

{
  "code": 0,
  "message": null,
  "recordTime": "2025-12-31T14:55:21Z",
  "data": {
    // Platform-specific data structure from Kuaishou API
  }
}

Field Descriptions

Raw JSON Philosophy

The tool intentionally returns unmodified upstream responses:

• ✅ Maximum data fidelity
• ✅ No field parsing or normalization
• ✅ No data restructuring
• ✅ Long-term compatibility

Sources: TOOLS.md:69-86

Usage Examples

Claude Desktop / Cursor

Search for "dance" videos on Kuaishou, page 1

MCP Host Tool Invocation

{
  "name": "kuaishou_search_video_v2",
  "input": {
    "keyword": "dance",
    "page": 1
  }
}

Expected Response Structure

{
  "code": 0,
  "message": null,
  "recordTime": "2025-01-15T10:30:00Z",
  "data": {
    // Kuaishou video search results
    // (exact structure determined by upstream API)
  }
}

Dependencies

The tool relies on the following npm packages:

Sources: package.json:18-26

Related Documentation

Related Pages

Related topics: Unified Search Tool, Kuaishou Video Search Tool

Tool Naming Conventions and Standards

Overview

The justoneapi-mcp project implements a standardized naming convention for all MCP (Model Context Protocol) tools. This convention ensures consistency, predictability, and scalability across the entire tool ecosystem. The naming standard follows a three-part pattern that clearly communicates the tool's scope, purpose, and version in a single identifier.

The primary objectives of this naming standard include:

• Discoverability: Tools can be easily identified and located based on their naming pattern
• Versioning: API evolution is managed through version suffixes
• Consistency: All contributors follow the same pattern, reducing cognitive load
• Scalability: New tools can be added following the established convention without ambiguity

Sources: README.md:73

Naming Pattern Structure

All tools in the justoneapi-mcp server follow a unified naming pattern:

{platform}_{action}_{version}

This three-component structure provides immediate context about each tool's purpose and scope.

Component Breakdown

Syntax Rules

1. Delimiter: Components are separated by underscores (_), not camelCase or hyphens
2. Lowercase: All components use lowercase letters exclusively
3. Compound actions: Multi-word actions use underscores (e.g., search_video)
4. Version format: Version uses lowercase v followed by a number (e.g., v1, v2)

Sources: README.md:74-76

Current Tool Registry

The following table lists all currently available tools in the justoneapi-mcp server:

Sources: src/index.ts:24-46

Platform Component Standards

Reserved Platform Identifiers

The platform component identifies the target service or search domain:

Sources: TOOLS.md:34-40

Naming Future Platforms

When adding new platforms, follow these guidelines:

1. Use the lowercase English name of the platform
2. If the platform name contains multiple words, use the most common short form
3. Avoid abbreviations unless they are universally recognized
4. Ensure uniqueness across all existing platform names

Action Component Standards

Single-Word Actions

Simple actions use a single lowercase word:

• search - General search functionality
• analyze - Data analysis operations
• fetch - Data retrieval operations

Compound Actions

Actions with multiple components use underscores to separate words:

Sources: src/tools/kuaishou/search_video_v2.ts:1-15

Version Component Standards

Versioning Strategy

The version component follows semantic versioning principles adapted for API evolution:

Version Upgrade Triggers

Consider incrementing the version when:

• Breaking API changes: Parameter types, required fields, or return structure change
• Behavior changes: Same inputs produce different outputs
• Deprecations: Removing functionality from a tool
• Major architectural changes: Internal refactoring affecting external behavior

Version Coexistence

Multiple versions of the same tool may coexist, allowing gradual migration:

• Old versions remain available for backward compatibility
• New versions receive new features and improvements
• Deprecation notices appear in documentation

Implementation Architecture

Tool Registration Flow

The following diagram illustrates how tools are registered and exposed through the MCP server:

graph TD
    A[Tool Definition File] --> B[Zod Input Schema]
    A --> C[Tool Handler Function]
    B --> D[registerTool in index.ts]
    C --> D
    D --> E[McpServer Instance]
    E --> F[STDIO Transport]
    F --> G[MCP Host Client]
    
    H[Tool Name: kuaishou_search_video_v2] --> D
    I[Tool Name: unified_search_v1] --> D

Tool Registration Code Structure

Tools are registered in src/index.ts using the MCP SDK's registerTool method:

server.registerTool(
  "kuaishou_search_video_v2",
  {
    description: "Search Kuaishou videos by keyword...",
    inputSchema: KuaishouSearchVideoV2Input.shape,
  },
  async (input) => {
    try {
      const data = await kuaishouSearchVideoV2(input);
      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
    } catch (e: unknown) {
      const m = toMcpErrorPayload(e);
      return { isError: true, content: [...] };
    }
  }
);

Sources: src/index.ts:24-46

Input Schema Conventions

Zod-Based Validation

All tools use Zod schemas for input validation, ensuring type safety and automatic documentation:

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"),
});

Schema Documentation Pattern

Each parameter includes:

Sources: src/tools/kuaishou/search_video_v2.ts:4-9

Unified Search Tool Specification

`unified_search_v1`

The unified search tool provides cross-platform search capabilities with advanced syntax support.

#### Parameters

#### Search Syntax Examples

Sources: src/tools/search/unified_search_v1.ts:1-42

Platform-Specific Tool Specification

`kuaishou_search_video_v2`

The Kuaishou video search tool provides platform-specific video search functionality.

#### Parameters

#### API Endpoint

GET /api/kuaishou/search-video/v2?token={token}&keyword={keyword}&page={page}

Sources: src/tools/kuaishou/search_video_v2.ts:1-15

Error Handling Integration

Standardized Error Codes

All tools return errors in a consistent format that includes the MCP error code:

ERROR[ERROR_CODE] (upstream=XXX): Human-readable message

Error Code Mapping

Sources: src/common/errors.ts:1-60

Error Handler Implementation

export function toMcpErrorPayload(e: unknown): {
  code: JOAErrorCode;
  message: string;
  upstreamCode?: number;
  httpStatus?: number;
} {
  const error = e as {
    name?: string;
    message?: string;
    upstreamCode?: number;
    httpStatus?: number;
  };
  
  if (error.name === "AbortError") {
    return { code: "NETWORK_TIMEOUT", message: buildUserMessage("NETWORK_TIMEOUT") };
  }
  // ... additional error type handling
}

Best Practices

Creating New Tools

Follow these steps to add a new tool:

1. Choose the name following the {platform}_{action}_{version} pattern
2. Create the tool file in src/tools/{platform}/
3. Define the Zod schema with descriptive parameter documentation
4. Implement the handler using getJson from common/http.ts
5. Register in index.ts with description and input schema
6. Add tests for input validation and error handling

File Naming Conventions

Documentation Requirements

Each tool must document:

• All parameters with types and descriptions
• Required vs optional parameters
• Default values where applicable
• Error codes that may be returned
• Example usage scenarios

Summary

The tool naming convention in justoneapi-mcp provides a clear, consistent, and scalable approach to defining MCP tools. By following the {platform}_{action}_{version} pattern, developers can quickly understand any tool's purpose and scope. The Zod-based schema validation ensures type safety, while standardized error handling provides consistent feedback across all operations.

Key takeaways:

• Use underscores to separate all components
• Always include the version suffix (v1, v2, etc.)
• Use compound action names with underscores when needed
• Follow the established file structure for organization
• Leverage Zod schemas for validation and documentation

Related Pages

Related topics: Authentication, HTTP Client Implementation

Configuration Reference

Overview

The justoneapi-mcp server provides a centralized configuration system that manages all runtime settings through environment variables. The configuration module serves as the single source of truth for API credentials, connection parameters, and debugging options.

Configuration is loaded from environment variables at startup and validated before the MCP server begins accepting requests. The system follows a "fail-fast" design pattern, terminating immediately if required parameters are missing.

Sources: src/index.ts:58-64

Environment Variables

Required Variables

The server validates the token presence on startup. If the token is missing or empty, the server exits with an error message directing users to set the environment variable.

Sources: src/index.ts:58-68

Optional Variables

Sources: README.md

Configuration Module Architecture

Module Structure

The configuration system consists of the following exported functions and objects:

// Implemented in src/common/config.ts
export const config: Config;        // Runtime configuration object
export function requireToken(): string;    // Validates and returns token
export function toSafeUrlForLog(url: string): string;  // Sanitizes URLs for logging

Configuration Object

The internal Config interface defines the shape of the runtime configuration:

interface Config {
  token: string;
  baseUrl: string;
  timeoutMs: number;
  retry: number;
  debug: boolean;
}

Token Management

Token Validation

The requireToken() function performs strict validation on the token:

1. Reads JUSTONEAPI_TOKEN from environment
2. Trims whitespace from the value
3. Checks if the token is empty
4. Returns the validated token string

If validation fails, an error is thrown immediately, preventing server startup.

Sources: src/common/config.ts

Token Usage in HTTP Layer

The token is used in HTTP requests by encoding it for URL safety:

const token = encodeURIComponent(requireToken());

This encoded token is appended to all API requests, including:

• Unified search: /api/search/v1?token=${token}&keyword=${keyword}
• Kuaishou video search: /api/kuaishou/search-video/v2?token=${token}&keyword=${keyword}

Sources: src/tools/search/unified_search_v1.ts

HTTP Layer Integration

Request Flow

graph TD
    A[API Tool Called] --> B[getJson Function]
    B --> C[requireToken Validation]
    C --> D[Build URL with Config]
    D --> E[Create AbortController]
    E --> F[Execute Fetch Request]
    F --> G{Success?}
    G -->|Yes| H[Parse JSON Response]
    G -->|No| I{Check Retryable Error}
    I -->|Yes| J[Wait 250ms × Attempt]
    J --> E
    I -->|No| K[Throw Error]
    H --> L[Return UpstreamResponse]
    K --> M[Error Handler]

Configuration Parameters Used

The HTTP module consumes configuration for request handling:

Sources: src/common/http.ts

Retry Mechanism

The retry logic uses the JUSTONEAPI_RETRY configuration value:

const attempts = 1 + Math.max(0, Number.isFinite(config.retry) ? config.retry : 0);

Retry occurs only for specific error types:

Sources: src/common/http.ts:31-39

Timeout Configuration

The timeout is applied using AbortController:

const timer = setTimeout(() => controller.abort(), config.timeoutMs);

With the default of 20000ms (20 seconds), requests exceeding this duration are cancelled and may be retried based on retry configuration.

Sources: src/common/http.ts:44-45

Debug Logging

When JUSTONEAPI_DEBUG is set to true, detailed request information is logged to stderr:

if (config.debug) {
  console.error(`[justoneapi] GET ${toSafeUrlForLog(url)} (attempt ${attempt}/${attempts})`);
}

URL Sanitization

The toSafeUrlForLog() function ensures tokens are never exposed in logs by sanitizing URLs before output.

Sources: src/common/config.ts

Error Handling Integration

Configuration errors are mapped to MCP error codes:

Sources: src/common/errors.ts

MCP Server Configuration

Claude Desktop Configuration

{
  "mcpServers": {
    "justoneapi": {
      "command": "npx",
      "args": ["-y", "justoneapi-mcp"],
      "env": {
        "JUSTONEAPI_TOKEN": "your_token_here",
        "JUSTONEAPI_TIMEOUT_MS": "30000",
        "JUSTONEAPI_DEBUG": "true"
      }
    }
  }
}

Configuration File Locations

Sources: README.md

Dependencies

The configuration system depends on the following packages:

Sources: package.json

Startup Validation

The server performs validation at startup in src/index.ts:

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);
  }
  // ... server initialization
}

This ensures users receive immediate feedback about missing configuration before the server attempts any network operations.

Sources: src/index.ts:58-68

Summary

The configuration system provides:

• Centralized management via environment variables
• Fail-fast validation on server startup
• Safe logging with token sanitization
• Configurable timeouts and retry behavior
• Debug capabilities for troubleshooting

All configuration flows through a single module (src/common/config.ts) ensuring consistent behavior across the entire application.

Related Pages

Related topics: Getting Started with JustOneAPI MCP

MCP Host Integration

Overview

MCP Host Integration refers to the process of connecting the justoneapi-mcp server to an MCP (Model Context Protocol) host application, enabling AI assistants like Claude Desktop, Cursor, or other MCP-compatible hosts to access Chinese social media search capabilities.

The integration follows the MCP specification, using JSON-RPC over stdio for communication between the host and server. This architecture allows any MCP-compatible host to discover and invoke the tools provided by justoneapi-mcp without custom integrations.

Sources: README.md:1-50

Architecture

System Components

The MCP Host Integration consists of three primary layers:

graph TD
    A["MCP Host<br/>(Claude Desktop, Cursor)"] --> B["justoneapi-mcp Server"]
    B --> C["JustOneAPI Backend"]
    B --> D["Zod Validation Layer"]
    
    A --> E["StdioServerTransport"]
    E --> B
    
    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#e8f5e9

Sources: src/index.ts:1-20

Request Flow

sequenceDiagram
    participant Host as MCP Host
    participant Server as justoneapi-mcp
    participant API as JustOneAPI
    
    Host->>Server: Tool invocation (JSON-RPC)
    Server->>Server: Validate with Zod schema
    Server->>API: HTTP request with token
    API->>API: Process search request
    API-->>Server: Raw JSON response
    Server-->>Host: JSON-RPC response

Supported MCP Hosts

The justoneapi-mcp server is compatible with any application implementing the MCP specification:

Sources: README.md:50-80

Installation and Configuration

Quick Start with npx

The recommended installation method uses npx for zero-configuration deployment:

{
  "mcpServers": {
    "justoneapi": {
      "command": "npx",
      "args": ["-y", "justoneapi-mcp"],
      "env": {
        "JUSTONEAPI_TOKEN": "your_token_here"
      }
    }
  }
}

Sources: README.md:60-75

Configuration Variables

Sources: README.md:130-145

Configuration File Locations

Sources: README.md:55-70

Tool Discovery

Discovery Mechanism

When the MCP host starts, the justoneapi-mcp server automatically registers all available tools. The host queries the server's capabilities and receives a manifest of all callable tools with their input schemas.

graph LR
    A[Host Startup] --> B[Initialize Stdio Transport]
    B --> C[Register Tools via SDK]
    C --> D[Handle list_tools Request]
    D --> E[Return Tool Manifest]
    
    F[User Request] --> G[Validate Input with Zod]
    G --> H[Execute Tool Handler]
    H --> I[Return JSON Response]

Available Tools

Sources: TOOLS.md:15-50

Discovery Command

To discover available tools in Claude Desktop:

Please list all available tools from justoneapi-mcp

Sources: README.md:35-45

Tool Input Validation

Schema Validation Flow

All tool inputs pass through Zod validation before execution:

graph TD
    A[User Input] --> B[Zod Schema Validation]
    B -->|Valid| C[Execute Tool Handler]
    B -->|Invalid| D[Return VALIDATION_ERROR]
    C --> E[API Request]
    E --> F[JSON Response]
    
    style D fill:#ffcdd2
    style F fill:#c8e6c9

Example: unified_search_v1 Schema

*Required for first page unless using nextCursor

Sources: src/tools/search/unified_search_v1.ts:10-45

Search Syntax Support

Sources: README.md:95-110

Error Handling Integration

Error Mapping

The server normalizes upstream errors into stable MCP error codes:

Sources: src/common/errors.ts:50-80

Error Response Format

ERROR[ERROR_CODE] (upstream=XXX): Human-readable message

Example:

ERROR[RATE_LIMITED] (upstream=302): Rate limit exceeded. Please slow down and retry later.

Sources: README.md:115-125

Retry Logic

The HTTP client implements automatic retry for transient failures:

Sources: src/common/http.ts:15-30

Session and Pagination

Cursor-Based Pagination

Search results use nextCursor for pagination to maintain state across requests:

graph LR
    A[First Request] -->|start + end| B[Page 1 Response]
    B -->|nextCursor| C[Second Request]
    C -->|nextCursor| D[Page 2 Response]
    D -->|nextCursor| E[Continue...]
    
    style A fill:#e3f2fd
    style D fill:#e8f5e9

Continuing Results

When results have more pages, simply ask:

• "Show me the next page of results"
• "Get more results from the previous search"
• "Continue with the next page"

The MCP host automatically extracts nextCursor and fetches subsequent pages without requiring start, end, or source parameters again.

Sources: README.md:78-92

Dependencies

Runtime Dependencies

Development Dependencies

Sources: package.json:15-35

Design Philosophy

Transport, Not Transformation

The justoneapi-mcp server adheres to a "Transport, not transformation" principle:

• Maximum data fidelity - Returns unmodified upstream responses
• No field parsing - Raw JSON from APIs
• No data restructuring - Preserves original schema
• Long-term compatibility - Schema stability over convenience

This ensures that:

1. No data is lost in translation
2. Users receive complete API responses
3. Breaking changes in upstream APIs are visible immediately
4. Advanced users can access any field from the response

Sources: README.md:155-165

Advanced Configuration Example

{
  "mcpServers": {
    "justoneapi": {
      "command": "npx",
      "args": ["-y", "justoneapi-mcp"],
      "env": {
        "JUSTONEAPI_TOKEN": "your_token_here",
        "JUSTONEAPI_TIMEOUT_MS": "30000",
        "JUSTONEAPI_DEBUG": "true",
        "JUSTONEAPI_RETRY": "3"
      }
    }
  }
}

Sources: README.md:145-155

Token Security

The server masks tokens in log output for security:

function maskToken(token: string): string {
  if (token.length <= 8) return "****";
  return token.slice(0, 4) + "****" + token.slice(-4);
}

Safe URL logging replaces the token parameter with masked value, ensuring credentials are never exposed in logs or error messages.

Sources: src/common/config.ts:30-45

Related Pages

Related topics: HTTP Client Implementation, Unified Search Tool, Configuration Reference

Error Handling

Overview

The justoneapi-mcp project implements a comprehensive error handling system designed to provide stability, transparency, and raw data fidelity. The error handling layer acts as a bridge between upstream API responses and MCP (Model Context Protocol) tool invocations, normalizing diverse error conditions into stable, actionable MCP error codes.

Key Design Principles:

• Transport, not transformation — the system prioritizes maximum data fidelity
• Fail fast with clear validation (token requirement checked early)
• Retry logic for transient failures
• Safe logging that never exposes sensitive credentials

Sources: README.md

Doramagic Pitfall Log

Doramagic extracted 7 source-linked risk signals. Review them before installing or handing real data to the project.

1. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | github_repo:1125683257 | https://github.com/justoneapi/justoneapi-mcp | README/documentation is current enough for a first validation pass.

2. Project risk: Clawhub skill family: 6 SKILL.md files have description-vs-body operation count mismatches (claim vs documented gap of…

• Severity: medium
• Finding: Project risk is backed by a source signal: Clawhub skill family: 6 SKILL.md files have description-vs-body operation count mismatches (claim vs documented gap of…. Treat it as a review item until the current version is checked.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/justoneapi/justoneapi-mcp/issues/2

3. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1125683257 | https://github.com/justoneapi/justoneapi-mcp | last_activity_observed missing

4. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | github_repo:1125683257 | https://github.com/justoneapi/justoneapi-mcp | no_demo; severity=medium

5. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.scoring_risks | github_repo:1125683257 | https://github.com/justoneapi/justoneapi-mcp | no_demo; severity=medium

6. Maintenance risk: issue_or_pr_quality=unknown

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1125683257 | https://github.com/justoneapi/justoneapi-mcp | issue_or_pr_quality=unknown

7. Maintenance risk: release_recency=unknown

• Severity: low
• Finding: release_recency=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1125683257 | https://github.com/justoneapi/justoneapi-mcp | release_recency=unknown

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using justoneapi-mcp with real data or production workflows.

• Clawhub skill family: 6 SKILL.md files have description-vs-body operatio - github / github_issue
• README/documentation is current enough for a first validation pass. - GitHub / issue