Singularity - MCP Discovery & Security Gateway

Singularity — MCP 发现与安全网关

MCP 版 Perplexity。 为问题找到合适的工具，查看其信任卡片 （提示词注入风险、权限越界、发布者状态），一键连接，并通过安全、可审计的网关执行——一款产品，一份配置。

完整计划请参阅 ROADMAP.md。蓝图：../Singularity_Blueprint.md。

快速开始（本地）

pip install -r requirements.txt
copy .env.example .env          # optional, defaults are fine (SQLite)
python scripts/seed_index.py    # builds index + embeddings (first run downloads ~35MB model)
python -m uvicorn app.main:app --reload   # http://127.0.0.1:8000/docs

全新启动且数据库为空时会自动播种——只有手动重新播种时才需要运行 seed_index.py。

将 Singularity 用作 MCP 服务

Singularity 是一个原生 MCP 服务（可流式传输的 HTTP、无状态），位于 /mcp。

VS Code / Copilot Chat — .vscode/mcp.json：

{ "servers": { "singularity": { "type": "http", "url": "http://127.0.0.1:8000/mcp" } } }

Cursor — ~/.cursor/mcp.json：

{ "mcpServers": { "singularity": { "url": "http://127.0.0.1:8000/mcp" } } }

Claude Code CLI：

claude mcp add --transport http singularity http://127.0.0.1:8000/mcp

然后只需向你的 Agent 提问：“我的团队需要费用跟踪”——它会调用 find_solutions 并返回按排名排列的选项，其中包含信任卡片和安全标记。

一键安装（部署后替换 URL）： 在 VS Code 中安装

/mcp 现在需要 OAuth（在 /authorize/<slug> 弹出的窗口会提供访问 令牌）。如需使用 curl 检查，请访问 /health 和 /.well-known/oauth-authorization-server。

工具

工具	功能
find_solutions(problem, top_k?, max_pricing_tier?)	按排名排列、经过信任评分的推荐，并附有通俗易懂的安全标记
get_trust_report(slug)	完整安全卡片：请求的权限与所需权限、注入扫描判定、发布者状态
compare_tools(slugs[])	入围候选项的并排信任表

每个结果都包含 fit_score、trust_score、rank_score、trust_flags 和 易于理解的 rationale。种子索引包含 quickledger-pro，这是一个故意投毒的虚构工具——询问费用相关问题，看看它如何被标记为 （suspicious_description_imperative、hidden_unicode_characters、permission_overreach），并在排名中被下调。

部署自己的实例（Render + Supabase）

完整操作指南请参阅 DEPLOY.md。概要：

1. 创建免费的 Supabase 项目 → 复制连接字符串 → 添加 +psycopg 驱动程序片段和 ?sslmode=require
2. 将此仓库推送到 GitHub → 在 Render 中选择“New +”→ “Blueprint”→ Render 会读取 render.yaml
3. 按提示将 Supabase URL 粘贴到 SINGULARITY_DATABASE_URL 环境变量中
4. 首次启动会自动创建表并为索引播种；https://<app>.onrender.com/mcp 即可访问

发布到 MCP 注册表

部署后（需要公开的 HTTPS），将 Singularity 列入目录，方便他人发现：

1. Official MCP Registry — 编辑 server.json 中的占位符 （将 XXXX 替换为你的 Render 应用名称），然后：

   npx mcp-publisher@latest init      # scaffolds/validates server.json
   npx mcp-publisher@latest login     # prove io.github.<you> ownership via GitHub
   npx mcp-publisher@latest publish   # listed at https://registry.modelcontextprotocol.io within minutes
   

2. Smithery — 在 https://smithery.ai/new 提交仓库（使用 smithery.yaml）
3. Glama — 在 https://glama.ai 提交远程 URL，然后认领该条目
4. GitHub topics — 为你的仓库添加 mcp-server、mcp、ai-security 主题；PulseMCP/MCP.so 爬虫会在 1–2 周内发现它

提示：注册表每周重新爬取一次，并会移除休眠服务的已验证徽章—— Render 的 $7/mo Starter 计划可确保 Singularity 在提交条目或面向投资者期间始终在线。

测试

pytest -v

目录结构

singularity/
  main.py                     FastAPI app factory + lifespan (auto-seed, mounts MCP)
  mcp_server.py               native MCP server: find_solutions / get_trust_report / compare_tools
  config.py                   env-driven settings (SINGULARITY_* prefix)
  database.py                 SQLAlchemy engine/session (SQLite dev, Postgres prod)
  models.py                   Tool + AuditLog tables
  schemas.py                  request/response contracts
  middleware/
    rate_limit.py             per-IP token-bucket limiter (X-Forwarded-For aware)
  services/
    discovery_engine.py       heuristic intent parsing
    recommendation_index.py   in-memory vector search over seeded tools
    ranking.py                fit/trust blend + rationale builder
    scanner.py                static injection/overreach scan (Phase 2 preview)
    seeder.py                 seed logic shared by CLI and boot-time auto-seed
    embeddings.py             fastembed provider (bge-small-en-v1.5)
  routers/
    recommend.py              POST /recommend, GET /tools
data/seed_tools.json          curated 21-tool index incl. demo attack sample (tier1/tier2/tier3)
scripts/seed_index.py         manual seeding CLI
scripts/smoke_execute.ps1     authenticated REST execute smoke test
scripts/smoke_oauth.py        OAuth discovery + config smoke test
Dockerfile / render.yaml      one-command Render deployment
server.json / smithery.yaml   registry publishing manifests (fill placeholders first)
tests/                        pytest suite (API + scanner + MCP tools & endpoint)