Skillporter-mcp

skillporter mcp runs a Model Context Protocol server over stdio. It lets an agent inspect the skills in the current workspace through structured tool calls, without shelling out.

The server is read-only unless you opt in to writes.

Register the server

Claude Code:

claude mcp add skillporter -- uvx skillporter mcp

Codex:

codex mcp add skillporter -- uvx skillporter mcp

Any client that reads an mcpServers configuration:

{
  "mcpServers": {
    "skillporter": {
      "command": "uvx",
      "args": ["skillporter", "mcp"]
    }
  }
}

The commands above assume uvx; the install page covers setup for uv, pipx and npx.

Tools

Tool	Access	Purpose
skillporter_diagnose	Read	Reachability, drift, duplicates and broken symlinks for the workspace.
skillporter_detect	Read	Which harnesses are installed or active.
skillporter_status	Read	Unified workspace environment snapshot (managed, unmanaged, orphaned and drifted skills).
skillporter_diff	Read	Compare the workspace against a .skillpack archive, directory or profile.
skillporter_scan	Read	Static security assessment of a skill directory.
skillporter_inspect	Read	Structure, metadata and security posture of a skill package.
skillporter_matrix	Read	The harness compatibility matrix.
skillporter_consolidate_preview	Read	Read-only report on instruction files: overlap, conflicts, outdated references and unclassified lines.
skillporter_context	Read	The instruction files and skills one harness loads, with estimated token cost.
skillporter_suggest	Read	Local stack detection and curated skill suggestions.
skillporter_insights	Read	Estimated token overhead of skills and instruction files.
skillporter_preview	Read	The content and path a harness would receive for a skill.
skillporter_add	Write	Resolve, scan and install a skill.
skillporter_install	Write	Install a local skill directory.
skillporter_sync	Write	Synchronize the workspace.
skillporter_remove	Write	Remove a skill.
skillporter_export	Write	Package the workspace skill environment into a .skillpack archive inside the workspace.
skillporter_import	Write	Validate and restore a workspace .skillpack archive.

All 18 tools are listed to the client. Five are new read-only tools; none of them writes to the workspace. If your agent harness supports SKILL.md directly rather than MCP, you can also install the official bundled Skillporter skill with skillporter self-skill install --harness detected. In the default MCP mode, calling a write tool returns an error and changes nothing:

error: MCP write operation 'skillporter_add' is disabled by default; launch with
\`skillporter mcp --allow-writes\` or set SKILLPORTER_MCP_ALLOW_WRITES=1 to authorize writes

Enabling writes

claude mcp add skillporter -- uvx skillporter mcp --allow-writes

Only do this when you want the agent to install and remove skills on its own. The write tools keep the same gates as the CLI:

• force only overwrites an existing destination.
• accept_risk is a separate boolean, and it is recorded in the audit log.
• Structural escapes cannot be accepted.
• A project skillporter.policy.yaml is enforced on skillporter_add and skillporter_install as it is on the CLI. See Policy and update review.
• skillporter_remove works without a harnesses argument and removes every Skillporter-managed copy. It keeps the original source.

Workspace boundary

The server treats tool arguments as untrusted, because they come from a model that may have read hostile content.

• The workspace root is fixed when the server starts: --root, then SKILLPORTER_MCP_ROOT, then the working directory.
• Every path argument is resolved and must stay inside that root. A request for ../.. is refused with an escapes workspace boundary error.
• UNC paths, Windows drive paths, NUL bytes and symlinks that leave the workspace are rejected.
• scope="user" is refused unless the server was started with --allow-user-scope.
• In read-only mode, skillporter_inspect only reads workspace paths. It will not fetch a remote repository unless SKILLPORTER_MCP_ALLOW_REMOTE=1 is set or writes are enabled.

Options

Flag	Environment variable	Effect
--root <dir>	SKILLPORTER_MCP_ROOT	Set the workspace boundary.
--allow-writes	SKILLPORTER_MCP_ALLOW_WRITES=1	Enable the write tools.
--allow-user-scope	SKILLPORTER_MCP_ALLOW_USER_SCOPE=1	Permit scope="user".
	SKILLPORTER_MCP_ALLOW_REMOTE=1	Permit remote sources for inspect in read-only mode.

Unknown arguments

Every tool schema is closed. A call that includes an argument the tool does not define, for example dry_run on skillporter_add, is rejected before anything runs, and the error names the argument. This stops a model from believing it requested a preview when the tool would have written files.

The server also answers ping, marks each tool in tools/list with readOnlyHint and destructiveHint annotations, and survives hostile input: a line over 8 MiB gets -32600, and deeply nested JSON gets -32700, with the server still running.

Type checking

Arguments are validated strictly. A boolean must be a JSON boolean, so "false" and "0" are rejected, not interpreted. Harness lists must contain registered harness IDs. Malformed JSON-RPC messages receive standard -32700 and -32600 errors.

Audit trail

Tool calls that change the workspace, and any accepted risk, are written to .skillporter/audit.jsonl with credentials scrubbed. Review them with:

skillporter audit .

Protocol details

The server speaks JSON-RPC 2.0 over stdio and reports MCP protocol version 2024-11-05.

Starting the server

skillporter mcp is the explicit form. Directory indexers and some MCP clients infer the launch command from the console script instead, spawning skillporter with no subcommand and a pipe on stdin. That invocation starts the server too, and prints one line to stderr so the choice is visible. A terminal, or a script that redirects /dev/null, still gets the help output rather than a server waiting on a pipe. glama.json at the repository root lists the maintainer who can claim the listing.

Registry listing

server.json at the repository root is the official MCP registry manifest (schema 2025-12-11). It registers io.github.Shanmukh-l33t/skillporter as the npm package @shanmukhdheekonda/skillporter, launched as npx -y @shanmukhdheekonda/skillporter mcp over stdio, read-only.

Keep the case of the GitHub account in the name (Shanmukh-l33t). Registry namespace grants are case-sensitive prefix matches, and GitHub authentication issues io.github.Shanmukh-l33t/*.

Publishing, as the owner:

curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
mcp-publisher login github          # device flow; from CI use login github-oidc
mcp-publisher validate server.json
mcp-publisher publish server.json

Ownership is proven by the mcpName field in the npm package that is actually published. npm 3.0.0 shipped without it, so that version cannot be registered. Publish a new npm version with the current package.json, set version and packages[].version in server.json to that version, then publish the manifest.