Panniantong/Agent-Reach · error · McporterConfigError

mcporter 配置不是有效的 UTF-8 JSON

Error message

mcporter 配置不是有效的 UTF-8 JSON

What it means

Raised when json.loads() on the read mcporter config text raises JSONDecodeError. The bytes were read and UTF-8-decoded fine, but the text is not valid JSON: trailing commas, comments, single quotes, unquoted keys, or truncation. (Message wording aside, decoding already succeeded — this is strictly a syntax failure.)

Source

Thrown at agent_reach/channels/mcporter.py:127

def _read_config_object(config_path: Path) -> dict:
    try:
        raw = read_small_text_no_follow(
            config_path,
            max_bytes=_MAX_CONFIG_BYTES,
        )
    except PrivatePathError as exc:
        raise McporterConfigError(
            f"mcporter 配置文件无法安全读取：{exc}"
        ) from exc
    except (OSError, UnicodeError) as exc:
        raise McporterConfigError("mcporter 配置文件无法安全读取") from exc
    if raw is None:
        raise McporterConfigError("mcporter 配置文件不存在")
    try:
        payload = json.loads(raw)
    except json.JSONDecodeError as exc:
        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 列表")

View on GitHub (pinned to 93ae1d18c3)

Solutions

1. Validate: jq . mcporter.json (or python -m json.tool) and fix the reported line/col
2. Remove comments and trailing commas; double-quote all keys and string values
3. If truncated, restore from VCS or regenerate the file

Example fix

// before
 {
   // my servers
   "mcpServers": { "fetch": { "command": "npx", } },
 }
// after
 {
   "mcpServers": { "fetch": { "command": "npx" } }
 }

import json

def config_json_valid(path) -> bool:
    try:
        json.load(open(path, encoding="utf-8"))
        return True
    except (ValueError, OSError, UnicodeError):
        return False

except McporterConfigError as exc:
    if isinstance(exc.__cause__, json.JSONDecodeError):
        show(f"syntax error at line {exc.__cause__.lineno} col {exc.__cause__.colno}")

When it happens

Trigger: Config contains JS-style JSON (comments, trailing commas, unquoted keys), is truncated mid-object, or has smart quotes from a word processor.

Common situations: JSON5/JSONC-style configs pasted from tutorials; secrets-injection template placeholders breaking string quoting; partial writes after crash.

Related errors

• mcporter 配置缺少 mcpServers 对象
• mcporter 配置包含无效的 server name
• mcporter server 定义必须是对象
• mcporter imports 必须是字符串列表
• mcporter 配置顶层必须是对象

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