spm搜索mcp
    
内置于 FastMCP 并使用 拱廊图案 以获得最佳的代理理解。
注（2026年3月）： 该项目目前处于搁置状态。它是作为使用HTML抓取和Cloudflare旁路进行代理SPI搜索的概念验证而构建的(curl_cffi).此后，旁路已被拆除——该项目现在使用普通httpx并且不再试图规避机器人保护，这意味着它实际上是不起作用的。看 为了上下文。如果API正式发布，项目将继续进行。
快速安装
从repo根目录运行MCP客户端的命令：
# Claude Desktop
fastmcp install claude-desktop src/spm_search_mcp/server.py:mcp --with-editable . -n "Swift Package Index"
# Claude Code
fastmcp install claude-code src/spm_search_mcp/server.py:mcp --with-editable . -n "Swift Package Index"
# Cursor
fastmcp install cursor src/spm_search_mcp/server.py:mcp --with-editable . -n "Swift Package Index"
# Any client — print the JSON snippet to paste
fastmcp install mcp-json src/spm_search_mcp/server.py:mcp --with-editable . -n "Swift Package Index"手动MCP客户端配置
通过GitHub（无需安装）
// add to your mcpServers:
"spm-search-mcp": {
"command": "uvx",
"args": [
"--from", "git+https://github.com/detailobsessed/spm-search-mcp",
"spm-search-mcp"
]
}需要 紫外线 (brew install uv 在macOS上）。
来源（开发）
// add to your mcpServers:
"spm-search-mcp": {
"command": "uv",
"args": [
"run",
"--with", "fastmcp",
"--with-editable", "/path/to/spm-search-mcp",
"fastmcp", "run",
"/path/to/spm-search-mcp/src/spm_search_mcp/server.py:mcp"
]
}工具
search_swift_packages
按关键字、作者、星级、平台、许可证等搜索Swift包。所有SPI 筛选器语法 作为类型化参数公开——代理永远不需要学习DSL。
| 参数 | 类型 | 说明 |
|---|---|---|
query | str | 自由文本搜索（例如。 "networking", "json parsing") |
author | str | 存储库所有者。前缀为 ! 排除（例如。 "!vapor") |
keyword | str | 包关键字标签。前缀为 ! 排除（例如。 "!deprecated") |
min_stars | int | GitHub最低星数 |
max_stars | int | GitHub最大星数 |
platforms | list | 兼容平台： ios, macos, watchos, tvos, visionos, linux |
license_filter | str | "compatible" 对于App Store，SPDX ID类似 "mit", "apache-2.0"，或前缀 ! 排除 |
last_activity_after | str | ISO8601日期--仅在此日期之后有效的包 |
last_activity_before | str | ISO8601日期--仅在此日期之前有效的包（与 after 对于一个窗口） |
last_commit_after | str | ISO8601日期--仅在此日期之后提交的包 |
last_commit_before | str | ISO8601日期--仅包含在此日期之前提交的包 |
product_type | str | library, executable, plugin，或 macro |
page | int | 分页页码（默认1） |
所有参数都是可选的。必须至少提供一个。参数与AND逻辑相结合。
list_search_filters
返回的有效值 platforms 和 product_type 参数。如果不确定接受哪些值，请先调用此函数。
_没有参数。_ 返回一个字典 platforms 和 product_types 钥匙。
get_package_readme
从GitHub获取包的README。默认情况下返回截断的内容（4000个字符）以保存令牌。
| 参数 | 类型 | 说明 |
|---|---|---|
owner | str | GitHub存储库所有者（例如。 "Alamofire") |
repo | str | GitHub存储库名称（例如。 "Alamofire") |
max_length | int | 要返回的最大字符数（默认值4000）。设置为 0 为了获得完整的内容。 |
示例用法
一旦连接，代理可以：
# 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)
# Discover valid platform and product_type values
list_search_filters()
# Browse a specific author's packages
search_swift_packages(author="apple")
# Exclude an author
search_swift_packages(query="networking", author="!vapor", min_stars=500)
# Exclude deprecated packages
search_swift_packages(query="json", keyword="!deprecated")
# Packages active in a date window (first half of 2024)
search_swift_packages(last_activity_after="2024-01-01", last_activity_before="2024-06-30", min_stars=100)
# Find abandoned packages (no commits since 2022)
search_swift_packages(last_commit_before="2022-01-01", min_stars=200)
# 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)错误处理
所有错误都返回结构化、可操作的消息，而不是原始异常：
- 可重试 --瞬态故障（超时、速率限制、服务器错误）。代理可以重试。
- 永久的 --请求本身是错误的（404403）。代理人应该改变其方法。
每个错误消息都会告诉代理发生了什么、原因以及如何修复。
设计
此服务器实现了以下功能 拱廊图案:
- 查询工具 --所有工具都是只读的，可以安全重试
- 发现工具 —
list_search_filters()在搜索之前公开有效的枚举值 - 受限输入 --平台和产品类型的枚举
- 智能故障 --所有参数都是可选的，具有合理的默认值
- NEXT_ACTION_HINT --每一个回应都暗示着下一步该做什么
- GUI_URL --每个结果都包含SPI+GitHub URL
- 令牌效率响应 --带有完整选项的截断README
- 分页结果 —
has_more带有页面导航的标志 - 错误分类 --可恢复与永久错误标记
- 恢复指南 --带有修复说明的可操作错误消息
- 进步_尾巴 —
max_length=0查看完整的README内容
发展
uv sync # install dependencies
uv run pytest # run 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