disvr CLAUDE.md

Disvr — Project Guide

Agent 智能服务发现引擎，帮 AI Agent 找到最值得用的工具。

Tech Stack

• Runtime: Cloudflare Workers
• Framework: Hono (TypeScript)
• Database: Cloudflare D1 (SQLite) + FTS5 全文搜索
• Vector Search: Cloudflare Vectorize (1536 dim, cosine)
• Embedding: OpenAI text-embedding-3-small
• MCP Server: CF Agents SDK (McpAgent class)
• Testing: Vitest v4.1.1

Key Commands

# Development
npx wrangler dev                    # Local dev server
npx vitest run                      # Run all tests (90 tests)
npx wrangler deploy                 # Deploy to production

# Database
npx wrangler d1 execute disvr-db --remote --command "SQL"
npx wrangler d1 execute disvr-db --file=./schema.sql  # Local reset

# Requires Node 22+
source ~/.nvm/nvm.sh && nvm use 22

Architecture

Request → Hono Router → Auth Middleware → Handler → D1/Vectorize → Response

Discovery Flow:
  need (string)
    → embedQuery (OpenAI) → vectorize.query (top 50)
    → getServicesByIds (D1) → applyConstraints → rankServices
    → top 3 recommendations with value scores

Ranking Weights:
  semantic: 0.30 | quality: 0.25 | cost_efficiency: 0.25 | reliability: 0.20

File Structure

src/
├── index.ts          # Hono app, routes, auth middleware
├── discover.ts       # Core search + ranking engine
├── db.ts             # D1 CRUD, stats, API key management
├── crawl.ts          # Multi-source crawlers (Smithery, GitHub, MCP Registry) + embedding
├── health.ts         # Automated health checks (GitHub, npm, PyPI, endpoint)
├── cooccurrence.ts   # Tool co-occurrence knowledge graph
├── alternatives.ts   # Deprecation detection & alternative recommendations
├── install-check.ts  # Install score: npm/pypi installability, env docs, difficulty rating
├── probe.ts          # Live probes: MCP handshake, HTTP API health check
├── benchmark.ts      # Benchmark engine: scoring, ranking, leaderboards
├── benchmark-scenarios.ts # 10 predefined benchmark scenario definitions
├── cost.ts           # Cost intelligence: pricing extraction, scoring, batch processing
├── error-taxonomy.ts # Error classification: status codes + text patterns → 10 error types
├── changelog.ts      # Version tracking: semver analysis, npm/pypi checks, breaking change detection
├── agent-profile.ts  # Agent behavioral profiling: usage tracking, personalized ranking
├── failover.ts       # Failover advisor: error-based decision engine + alternative lookup
├── watch.ts          # Tool watch & alerts: subscriptions, alert generation, pull-based notifications
├── mcp.ts            # MCP Server (6 tools: discover, details, report, list, failover, alternatives)
├── types.ts          # All TypeScript types + rowToService
├── landing.ts        # Landing page HTML
└── pages/
    ├── registry.ts   # Searchable service directory
    ├── explorer.ts   # Interactive API playground
    ├── analytics.ts  # Real-time dashboard
    ├── benchmark.ts  # Benchmark leaderboard page
    ├── service-detail.ts # Service detail page (dynamic, all data sections)
    └── keys.ts       # API key registration
test/
├── types.test.ts     # 8 tests
├── discover.test.ts  # 12 tests
├── db.test.ts        # 17 tests
├── api.test.ts       # 24 tests
├── crawl.test.ts     # 7 tests
├── health.test.ts    # 28 tests
├── cooccurrence.test.ts # co-occurrence tests
├── alternatives.test.ts # deprecation & alternatives tests
├── install-check.test.ts # install score tests
├── probe.test.ts     # live probe tests
├── benchmark.test.ts # benchmark scoring & scenarios tests
├── cost.test.ts      # cost intelligence tests
├── error-taxonomy.test.ts # error classification tests (51 tests)
├── changelog.test.ts # version tracking & breaking change tests (33 tests)
├── agent-profile.test.ts # agent profiling & personalization tests (22 tests)
├── frontend-enhance.test.ts # frontend enhancement tests (14 tests)
├── failover.test.ts  # failover advisor tests (28 tests)
└── watch.test.ts     # tool watch & alerts tests