Panniantong/Agent-Reach · error · McporterConfigError

mcporter imports 必须是字符串列表

Error message

mcporter imports 必须是字符串列表

What it means

Raised when a config layer's 'imports' key exists but is not a list of strings. Doctor treats imports as an honesty flag: when imports are present (or omitted, since mcporter then auto-imports editor configs), it marks the inspection imports_unchecked because imported files may add servers it did not open. Malformed imports abort instead of producing a misleading result.

Source

Thrown at agent_reach/channels/mcporter.py:73

        if not isinstance(servers, dict):
            raise McporterConfigError("mcporter 配置缺少 mcpServers 对象")

        for name, definition in servers.items():
            if not isinstance(name, str) or not name.strip():
                raise McporterConfigError("mcporter 配置包含无效的 server name")
            if not isinstance(definition, dict):
                raise McporterConfigError("mcporter server 定义必须是对象")
            names.add(name.casefold())

        imports = payload.get("imports", _MISSING)
        if imports is _MISSING:
            # mcporter defaults to importing supported editor configs when the
            # key is omitted. Doctor intentionally does not open those files.
            imports_unchecked = True
        elif not isinstance(imports, list) or not all(
            isinstance(item, str) for item in imports
        ):
            raise McporterConfigError("mcporter imports 必须是字符串列表")
        elif imports:
            imports_unchecked = True
        sources.append(source)

    return McporterConfigInspection(
        frozenset(names),
        "+".join(sources),
        imports_unchecked=imports_unchecked,
    )


def _select_config_layers(
    root_dir: str | Path | None,
) -> list[tuple[Path, str]]:
    root = Path(os.path.abspath(os.fspath(root_dir or Path.cwd())))
    explicit = os.environ.get("MCPORTER_CONFIG", "").strip()
    if explicit:
        expanded = Path(os.path.expanduser(explicit))

View on GitHub (pinned to 93ae1d18c3)

Solutions

1. Write imports as an array of path strings: '"imports": ["../shared/mcp.json"]'
2. Remove the imports key if you do not import anything (but know the doctor will then flag imports_unchecked due to mcporter's auto-import default)
3. Check every layer — user config and project .mcporter/mcporter.json both

Example fix

// before
 { "mcpServers": {}, "imports": "./extra.json" }
// after
 { "mcpServers": {}, "imports": ["./extra.json"] }

import json

def imports_ok(path) -> bool:
    try:
        payload = json.load(open(path, encoding="utf-8"))
    except Exception:
        return False
    if "imports" not in payload:
        return True
    imports = payload["imports"]
    return isinstance(imports, list) and all(isinstance(i, str) for i in imports)

def valid_imports(payload: dict) -> bool:
    imports = payload.get("imports")
    return imports is None or (isinstance(imports, list) and all(isinstance(x, str) for x in imports))

except McporterConfigError as exc:
    if "imports" in str(exc):
        show_fix("change imports to an array of path strings")

When it happens

Trigger: Any selected layer has '"imports": "../shared.json"' (string), '"imports": {"a": 1}' (object), or a list containing non-strings like '"imports": [1]'. Note: 'imports': [] (empty list) is accepted and NOT flagged unchecked.

Common situations: Confusion with YAML anchors or glob strings written as a single string; older/newer mcporter schema drift where imports was an object map; hand-merging several config files.

Related errors

• mcporter 配置缺少 mcpServers 对象
• mcporter 配置包含无效的 server name
• mcporter server 定义必须是对象
• mcporter 配置不是有效的 UTF-8 JSON
• mcporter 配置顶层必须是对象

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