Bug: skillspector mcp stdio server hangs during MCP initialize under Codex

[poorlyordered]

Summary

skillspector mcp does not currently start successfully as a Codex stdio MCP server in my environment.

There were two distinct failure modes:

1. Installing SkillSpector with the documented quick install gives a working CLI, but not a working MCP server because the optional mcp dependency is missing.
2. Reinstalling with the mcp extra fixes the missing dependency, but the stdio MCP server stays alive and never responds to the MCP initialize request.

Environment

• OS: WSL/Linux
• Python used by uv tool after reinstall: Python 3.12.3
• SkillSpector: 2.3.5
• MCP SDK after fresh extra install: 1.28.0
• Install source: git+https://github.com/NVIDIA/skillspector.git
• Client: Codex MCP stdio server registration

Current tool environment check:

/home/frosted639/.local/share/uv/tools/skillspector/bin/python
skillspector 2.3.5
mcp 1.28.0

Reproduction

Install and register as a Codex stdio MCP server:

uv tool install git+https://github.com/NVIDIA/skillspector.git
codex mcp add skillspector -- skillspector mcp

Starting Codex reports:

MCP client for `skillspector` failed to start:
MCP startup failed: handshaking with MCP server failed:
connection closed: initialize response

Manual reproduction showed the command exits with code 2:

Error: The MCP server requires the optional 'mcp' dependency. Install it with:
pip install 'skillspector[mcp]'

Reinstalling with the extra fixes that part:

uv tool install --force --python 3.12 \
  'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'

After that, the process no longer exits, but it does not complete the MCP handshake. Using the Python MCP SDK client against skillspector mcp times out waiting for initialize.

Minimal probe:

import anyio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    with anyio.fail_after(15):
        params = StdioServerParameters(command="skillspector", args=["mcp"])
        async with stdio_client(params) as (read, write):
            async with ClientSession(read, write) as session:
                result = await session.initialize()
                print("initialized", result.serverInfo.name, result.serverInfo.version)
                tools = await session.list_tools()
                print("tools", [tool.name for tool in tools.tools])

anyio.run(main)

Result:

TimeoutError

I also tested a minimal FastMCP stdio server in the same uv tool environment, and it similarly timed out during initialize. A lower-level test suggested the stdio server path is waiting on anyio.wrap_file(sys.stdin) and not receiving the piped line in this environment.

Expected Behavior

After installing with the mcp extra, skillspector mcp should respond to MCP initialize and expose the scan_skill tool over stdio.

Actual Behavior

• Without the extra: the server exits immediately because mcp is missing.
• With the extra: the server remains alive but never responds to initialize.

Workaround

I removed the Codex MCP registration and kept using the CLI directly:

codex mcp remove skillspector
skillspector scan <target> --no-llm

The CLI scanner works; the stdio MCP server is the failing path.

Notes

It may be helpful for the docs to make the MCP install path prominent, e.g. uv tool install 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git', because the regular CLI install succeeds but leaves skillspector mcp unable to start.