spm-search-mcp

An MCP server that lets coding agents search the Swift Package Index. No API key required.

Built with FastMCP and designed using arcade patterns for optimal agent comprehension.

Quick install

The fastest way to add this server to your MCP client:

# Claude Desktop
uvx fastmcp install claude-desktop spm_search_mcp/server.py:mcp -n "Swift Package Index"

# Claude Code
uvx fastmcp install claude-code spm_search_mcp/server.py:mcp -n "Swift Package Index"

# Cursor
uvx fastmcp install cursor spm_search_mcp/server.py:mcp -n "Swift Package Index"

# Any client — get the JSON snippet to paste
uvx fastmcp install mcp-json spm_search_mcp/server.py:mcp -n "Swift Package Index"

Manual MCP client configuration

Published package (once on PyPI)

{
  "mcpServers": {
    "spm-search": {
      "command": "uvx",
      "args": ["spm-search-mcp"]
    }
  }
}

From source (development)

{
  "mcpServers": {
    "spm-search": {
      "command": "uv",
      "args": [
        "run",
        "--with", "fastmcp",
        "--with-editable", "/path/to/spm-search",
        "fastmcp", "run",
        "/path/to/spm-search/src/spm_search_mcp/server.py:mcp"
      ]
    }
  }
}

Tools

search_swift_packages

Search for Swift packages by keyword, author, stars, platform, license, and more. All of SPI's filter syntax is exposed as typed parameters — agents never need to learn the DSL.

All parameters are optional. At least one must be provided. Parameters combine with AND logic.

get_package_readme

Fetch a package's README from GitHub. Returns truncated content by default (4000 chars) to save tokens.

Example usage

Once connected, an agent can:

# Search for networking libraries with 500+ stars
search_swift_packages(query="networking", min_stars=500)

# Find iOS-compatible packages
search_swift_packages(platforms=["ios"], min_stars=100)

# Browse a specific author's packages
search_swift_packages(author="apple")

# Read a package's README
get_package_readme(owner="Alamofire", repo="Alamofire")

# Get full README (no truncation)
get_package_readme(owner="apple", repo="swift-nio", max_length=0)

Error handling

All errors return structured, actionable messages instead of raw exceptions:

• RETRYABLE — transient failures (timeouts, rate limits, server errors). The agent can retry.

• PERMANENT — the request itself is wrong (404, 403). The agent should change its approach.

Every error message tells the agent what happened, why, and how to fix it.

Design

This server implements these arcade patterns:

• QUERY_TOOL — both tools are read-only, safe to retry

• CONSTRAINED_INPUT — enums for platforms and product types

• SMART_DEFAULTS — all parameters optional with sensible defaults

• NEXT_ACTION_HINT — every response suggests what to do next

• GUI_URL — every result includes SPI + GitHub URLs

• TOKEN_EFFICIENT_RESPONSE — truncated README with opt-in full

• PAGINATED_RESULT — has_more flag with page navigation

• ERROR_CLASSIFICATION — RETRYABLE vs PERMANENT error tagging

• RECOVERY_GUIDE — actionable error messages with fix instructions

• PROGRESSIVE_DETAIL — max_length=0 for full README content

Development

uv sync                  # install dependencies
uv run pytest            # run tests (62 tests)
uv run poe test-cov      # run with coverage (90%+ required)
uv run ruff check .      # lint
uv run ty check .        # type check
prek run --all-files     # run all pre-commit hooks