Panniantong/Agent-Reach · error · McporterConfigError

mcporter JSON 缺少 servers 列表

Error message

mcporter JSON 缺少 servers 列表

What it means

Raised by configured_server_names(output) when the parsed mcporter JSON is a dict but its 'servers' value is missing or not a list. mcporter's --json contract is an object like {"servers": [{"name": ...}, ...]}; anything else (different key name, servers as object, empty output '{}') fails this shape check before name extraction.

Source

Thrown at agent_reach/channels/mcporter.py:145

        raise McporterConfigError("mcporter 配置不是有效的 UTF-8 JSON") from exc
    if not isinstance(payload, dict):
        raise McporterConfigError("mcporter 配置顶层必须是对象")
    return payload


def configured_server_names(output: str) -> set[str]:
    """Return exact configured server names from ``mcporter ... --json``.

    Paths, descriptions, endpoints, and other metadata are deliberately
    ignored: only each server object's ``name`` field is a routing signal.
    """
    try:
        payload = json.loads(output)
    except (json.JSONDecodeError, TypeError) as exc:
        raise McporterConfigError("mcporter 返回的 JSON 无法解析") from exc

    if not isinstance(payload, dict) or not isinstance(payload.get("servers"), list):
        raise McporterConfigError("mcporter JSON 缺少 servers 列表")

    return {
        name.casefold()
        for server in payload["servers"]
        if isinstance(server, dict)
        if isinstance(name := server.get("name"), str) and name.strip()
    }

View on GitHub (pinned to 93ae1d18c3)

Solutions

1. Print the raw mcporter JSON output and compare against the expected {"servers": [...]} shape
2. Pin or upgrade mcporter to a version compatible with Agent Reach (check Agent Reach release notes / doctor)
3. If mcporter returned an error payload, fix the underlying mcporter error first (auth, missing config)
4. Report a schema change to Agent Reach if upstream mcporter changed its --json contract

Example fix

# before: mcporter --json prints {"status":"ok"}
# after (mcporter list --json prints)
 {"servers": [{"name": "fetch"}, {"name": "github"}]}

import json

def output_has_servers_list(output) -> bool:
    try:
        payload = json.loads(output)
    except (ValueError, TypeError):
        return False
    return isinstance(payload, dict) and isinstance(payload.get("servers"), list)

def is_mcporter_listing(payload) -> bool:
    return isinstance(payload, dict) and isinstance(payload.get("servers"), list)

except McporterConfigError as exc:
    if "servers 列表" in str(exc):
        check_mcporter_version_and_schema()  # pin a compatible release

When it happens

Trigger: mcporter emits {"status":"ok"} (no servers key), {"servers": {"a":{}}} (object not list), or a newer schema renaming the key. Empty list '[]' is valid — returns empty set, no error.

Common situations: mcporter version change altering the --json schema; command succeeded but reported an error payload (error JSON without servers); wrong subcommand whose JSON output has a different shape.

Related errors

• mcporter 返回的 JSON 无法解析
• mcporter 配置缺少 mcpServers 对象
• mcporter 配置包含无效的 server name
• mcporter server 定义必须是对象
• mcporter imports 必须是字符串列表

AI-assisted analysis of Panniantong/Agent-Reach@93ae1d18c3 (2026-08-14). Data as JSON: /api/errors/ebb6330593cd118d. Report an issue: GitHub.