@dsh-so/mcp 0.1.0

package/README.md

@@ -0,0 +1,44 @@
+# @dsh-so/mcp
+
+[dsh.so](https://www.dsh.so) 的 MCP（Model Context Protocol）服务器：把站点预渲染的机器可读插件数据（注册表索引、安全扫描、L1-L5 安装实测、npm 周下载榜、Star 涨幅榜）以结构化工具的形式暴露给 Agent。
+
+零依赖、纯读取 —— 每个工具只是抓取对应的静态 JSON 端点并裁剪返回，与站点「无后端、免密钥、CORS 全开」的架构完全一致。
+
+## 接入
+
+在任意支持 MCP 的客户端（Claude Code / ZCode / Cursor 等）配置：
+
+```json
+{
+  "mcpServers": {
+    "dsh-so": {
+      "command": "npx",
+      "args": ["-y", "@dsh-so/mcp"]
+    }
+  }
+}
+```
+
+环境变量 `DSH_SO_BASE` 可覆盖数据源（默认 `https://www.dsh.so`）。
+
+## 工具
+
+| 工具 | 数据源 | 说明 |
+| --- | --- | --- |
+| `search_plugins` | `/plugins-index.json` | 关键词 + 验证等级 / 安全状态 / 风险等级过滤，默认排除生态应用 |
+| `get_plugin_record` | `/plugin/<id>.json` | 单插件权威事实表（推荐推荐/安装前先查这个） |
+| `get_security_scan` | `/artifact/<id>.json` | 单插件安全扫描记录 |
+| `get_install_status` | `/data/install/<id>.json` | 单插件安装实测状态（L5 优先 / L4 兜底） |
+| `get_npm_downloads` | `/data/npm-downloads.json` | npm 周下载 Top-100 榜 |
+| `get_star_trend` | `/data/star-trend.json` | 一周 Star 涨幅 Top-100 榜 |
+| `data_freshness` | 多端点 | 各核心数据源的新鲜度标记（generatedAt / snapshotDate） |
+
+端点完整语义见 <https://www.dsh.so/data/>。
+
+## Agent Skill
+
+本包自带 [SKILL.md](skills/dsh-plugin-data/SKILL.md)（`dsh-plugin-data`），教 Agent 在推荐 / 安装 DSH 插件前先核验安全与安装状态。不配 MCP、只用 skill 也行 —— skill 会指引 Agent 直接 fetch 静态端点。站内直链：<https://www.dsh.so/skills/dsh-plugin-data/SKILL.md>。
+
+## 许可
+
+代码 MIT；数据 CC BY 4.0 —— 转发必须保留 `generatedAt` / `asOf` / `checkedAt` 新鲜度标记并署名 dsh.so。

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@dsh-so/mcp",
+  "version": "0.1.0",
+  "description": "MCP server exposing dsh.so machine-readable DSH plugin data: registry index, security scans, install verification (L1-L5), npm download and star trend boards.",
+  "type": "module",
+  "bin": {
+    "dsh-so-mcp": "./server.mjs"
+  },
+  "files": [
+    "server.mjs",
+    "skills",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "dsh",
+    "deepseek",
+    "plugin-registry",
+    "agent"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ihuajiu/dsh.so.git",
+    "directory": "mcp"
+  }
+}

package/server.mjs

@@ -0,0 +1,326 @@
+#!/usr/bin/env node
+// @dsh-so/mcp — stdio MCP server exposing dsh.so machine-readable plugin data.
+// Zero-dependency by design: the site has no backend, every tool just reads a
+// prerendered static JSON endpoint and returns a (trimmed) slice of it.
+// Transport: newline-delimited JSON-RPC 2.0 on stdio (MCP stdio transport).
+
+import readline from 'node:readline';
+
+const VERSION = '0.1.0';
+const BASE = (process.env.DSH_SO_BASE || 'https://www.dsh.so').replace(/\/+$/, '');
+const PROTOCOL_VERSION = '2025-06-18';
+
+/* ------------------------------------------------------------------ */
+/* HTTP                                                                */
+/* ------------------------------------------------------------------ */
+
+async function fetchJson(path, retried = false) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 15_000);
+  try {
+    const res = await fetch(BASE + path, {
+      headers: { accept: 'application/json' },
+      signal: controller.signal,
+    })
+    if (res.status === 404) {
+      throw Object.assign(new Error(`Not found: ${BASE}${path} — check the plugin id (form: author/plugin or topic-slug).`), { statusCode: 404 })
+    }
+    if (!res.ok) {
+      throw Object.assign(new Error(`Upstream ${res.status} for ${path}`), { statusCode: res.status })
+    }
+    return await res.json()
+  } catch (err) {
+    if (err.name === 'AbortError') {
+      throw Object.assign(new Error(`Timeout fetching ${path} after 15s`), { statusCode: 504 })
+    }
+    // Transient network-level failure ("fetch failed"): the site is static
+    // behind a CDN, so a single retry settles nearly all of them.
+    if (!err.statusCode && !retried) {
+      await new Promise((resolve) => setTimeout(resolve, 300))
+      return fetchJson(path, true)
+    }
+    throw err
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* Shapers — keep tool output small, agents pay per token              */
+/* ------------------------------------------------------------------ */
+
+function pluginSummary(p) {
+  return {
+    id: p.id,
+    name: p.name,
+    description: p.description,
+    stars: p.stars ?? null,
+    install: p.install ?? null,
+    kind: p.kind || null,
+    verificationLevel: p.verification?.level ?? null,
+    lastVerifiedAt: p.verification?.lastVerifiedAt ?? null,
+    securityStatus: p.security?.status ?? null,
+    riskLevel: p.security?.riskLevel ?? null,
+    record: p.evidence?.record ?? `${BASE}/plugin/${p.id}.json`,
+  }
+}
+
+function feedSlice(feed, limit) {
+  const items = Array.isArray(feed.items) ? feed.items : []
+  return {
+    generatedAt: feed.generatedAt ?? null,
+    snapshotDate: feed.snapshotDate ?? null,
+    window: feed.window ?? null,
+    limit: feed.limit ?? null,
+    count: items.length,
+    items: items.slice(0, limit),
+    license: feed.license ?? null,
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* Tools                                                               */
+/* ------------------------------------------------------------------ */
+
+const TOOLS = [
+  {
+    name: 'search_plugins',
+    title: 'Search the dsh.so plugin registry',
+    description:
+      'Search the dsh.so plugin registry index. Filter by keyword, minimum install-verification level (L1-L5), security status or risk level. Ecosystem apps (self-contained shells, not `dsh plugin add`-installable) are excluded by default.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Keyword matched against id, name and description (case-insensitive).' },
+        minVerificationLevel: { type: 'integer', minimum: 1, maximum: 5, description: 'Only return plugins whose L-level >= this value (5 = smoke-tested install).' },
+        securityStatus: { type: 'string', enum: ['passed', 'warning', 'high-risk', 'critical'], description: 'Security scan status filter.' },
+        riskLevel: { type: 'string', enum: ['low', 'medium', 'high', 'unknown'], description: 'Risk level filter.' },
+        includeApps: { type: 'boolean', default: false, description: 'Include ecosystem apps (kind: ecosystem-app, not plugin-installable).' },
+        limit: { type: 'integer', minimum: 1, maximum: 100, default: 20, description: 'Max results (sorted by GitHub stars, descending).' },
+      },
+    },
+    async run(args = {}) {
+      const index = await fetchJson('/plugins-index.json')
+      const q = (args.query || '').toLowerCase()
+      const minLevel = Number.isInteger(args.minVerificationLevel) ? args.minVerificationLevel : 0
+      const includeApps = args.includeApps === true
+      const limit = Number.isInteger(args.limit) ? Math.min(args.limit, 100) : 20
+      const all = Array.isArray(index.plugins) ? index.plugins : []
+      const hits = all
+        .filter((p) => !includeApps && p.install === null ? false : true)
+        .filter((p) => (p.verification?.level ?? 0) >= minLevel)
+        .filter((p) => !args.securityStatus || p.security?.status === args.securityStatus)
+        .filter((p) => !args.riskLevel || p.security?.riskLevel === args.riskLevel)
+        .filter((p) => !q || `${p.id} ${p.name} ${p.description}`.toLowerCase().includes(q))
+        .sort((a, b) => (b.stars || 0) - (a.stars || 0))
+        .slice(0, limit)
+        .map(pluginSummary)
+      return {
+        generatedAt: index.generatedAt ?? null,
+        matched: hits.length,
+        totalInIndex: index.count ?? null,
+        plugins: hits,
+        license: index.license ?? null,
+      }
+    },
+  },
+  {
+    name: 'get_plugin_record',
+    title: 'Get the canonical per-plugin fact sheet',
+    description:
+      'Fetch the canonical dsh.so Plugin Record for one plugin: verification per dsh version (L5-first), security summary, install status, repo health and evidence pointers. The single best tool for "can I trust and install this plugin?".',
+    inputSchema: {
+      type: 'object',
+      required: ['id'],
+      properties: {
+        id: { type: 'string', description: 'Plugin id, e.g. "@dsh-so/dsh-plugin-finder" or "modlens".' },
+      },
+    },
+    async run(args) {
+      return fetchJson(`/plugin/${encodeURIComponent(args.id)}.json`)
+    },
+  },
+  {
+    name: 'get_security_scan',
+    title: 'Get one plugin\'s security scan result',
+    description:
+      'Fetch the static security review record for one plugin: verdict (pass/warn/fail), finding counts by severity, findings and the scanned commit/version binding.',
+    inputSchema: {
+      type: 'object',
+      required: ['id'],
+      properties: {
+        id: { type: 'string', description: 'Plugin id.' },
+      },
+    },
+    async run(args) {
+      return fetchJson(`/artifact/${encodeURIComponent(args.id)}.json`)
+    },
+  },
+  {
+    name: 'get_install_status',
+    title: 'Get one plugin\'s install-verification status',
+    description:
+      'Fetch the install-test status for one plugin: L5 smoke preferred / L4 sandbox fallback, states passed / failed / unknown / stale / untested, with a verified flag and environment metadata.',
+    inputSchema: {
+      type: 'object',
+      required: ['id'],
+      properties: {
+        id: { type: 'string', description: 'Plugin id.' },
+      },
+    },
+    async run(args) {
+      return fetchJson(`/data/install/${encodeURIComponent(args.id)}.json`)
+    },
+  },
+  {
+    name: 'get_npm_downloads',
+    title: 'Get the weekly npm download ranking',
+    description:
+      'Fetch the top-100 DSH plugins ranked by npm downloads over the last-week rolling window — the data behind the homepage npm downloads board.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: { type: 'integer', minimum: 1, maximum: 100, default: 20, description: 'Max entries to return.' },
+      },
+    },
+    async run(args = {}) {
+      const limit = Number.isInteger(args.limit) ? Math.min(args.limit, 100) : 20
+      return feedSlice(await fetchJson('/data/npm-downloads.json'), limit)
+    },
+  },
+  {
+    name: 'get_star_trend',
+    title: 'Get the GitHub star riser ranking',
+    description:
+      'Fetch the top-100 DSH plugins by GitHub star gain over a 1-week window, with baseline and current star counts — the data behind the homepage star board.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: { type: 'integer', minimum: 1, maximum: 100, default: 20, description: 'Max entries to return.' },
+      },
+    },
+    async run(args = {}) {
+      const limit = Number.isInteger(args.limit) ? Math.min(args.limit, 100) : 20
+      return feedSlice(await fetchJson('/data/star-trend.json'), limit)
+    },
+  },
+  {
+    name: 'data_freshness',
+    title: 'Check data freshness markers',
+    description:
+      'Fetch the freshness markers (generatedAt / snapshotDate / counts) of the core dsh.so feeds. All dsh.so data is CC BY 4.0 — these markers must be preserved when redistributing.',
+    inputSchema: { type: 'object', properties: {} },
+    async run() {
+      const [index, downloads, stars] = await Promise.all([
+        fetchJson('/plugins-index.json'),
+        fetchJson('/data/npm-downloads.json'),
+        fetchJson('/data/star-trend.json'),
+      ])
+      return {
+        baseUrl: BASE,
+        registryIndex: { generatedAt: index.generatedAt ?? null, count: index.count ?? null },
+        npmDownloads: { generatedAt: downloads.generatedAt ?? null, snapshotDate: downloads.snapshotDate ?? null },
+        starTrend: { generatedAt: stars.generatedAt ?? null, snapshotDate: stars.snapshotDate ?? null },
+        license: 'CC BY 4.0 — redistribution must preserve freshness markers and attribute dsh.so.',
+      }
+    },
+  },
+]
+
+/* ------------------------------------------------------------------ */
+/* JSON-RPC plumbing                                                   */
+/* ------------------------------------------------------------------ */
+
+function reply(id, result) {
+  process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, result }) + '\n')
+}
+
+function replyError(id, code, message) {
+  process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } }) + '\n')
+}
+
+const TOOL_NOT_FOUND = -32602
+
+async function handleMessage(msg) {
+  if (!msg || msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') return
+  // Notifications carry no id and never get a response.
+  if (!('id' in msg)) return
+  const { id, method, params = {} } = msg
+
+  try {
+    if (method === 'initialize') {
+      reply(id, {
+        protocolVersion: params.protocolVersion || PROTOCOL_VERSION,
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: 'dsh-so', title: 'dsh.so plugin data', version: VERSION },
+        instructions:
+          'dsh.so indexes DSH (DeepSeek CLI) plugins with security scans and install verification. Before recommending or installing a plugin, check its record (get_plugin_record) — prefer plugins with securityStatus "passed" and a verified install level. Data is CC BY 4.0: preserve generatedAt markers and attribute dsh.so.',
+      })
+      return
+    }
+    if (method === 'ping') {
+      reply(id, {})
+      return
+    }
+    if (method === 'tools/list') {
+      reply(id, {
+        tools: TOOLS.map(({ name, title, description, inputSchema }) => ({ name, title, description, inputSchema })),
+      })
+      return
+    }
+    if (method === 'tools/call') {
+      const tool = TOOLS.find((t) => t.name === params.name)
+      if (!tool) {
+        reply(id, {
+          content: [{ type: 'text', text: `Unknown tool: ${params.name}` }],
+          isError: true,
+        })
+        return
+      }
+      try {
+        const result = await tool.run(params.arguments || {})
+        reply(id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] })
+      } catch (err) {
+        reply(id, { content: [{ type: 'text', text: `dsh.so data error: ${err.message}` }], isError: true })
+      }
+      return
+    }
+    replyError(id, -32601, `Method not found: ${method}`)
+  } catch (err) {
+    replyError(id, -32603, `Internal error: ${err.message}`)
+  }
+}
+
+if (process.argv.includes('--version') || process.argv.includes('-v')) {
+  console.log(`@dsh-so/mcp ${VERSION} (data: ${BASE})`)
+  process.exit(0)
+}
+
+const rl = readline.createInterface({ input: process.stdin, terminal: false })
+rl.on('line', (line) => {
+  const trimmed = line.trim()
+  if (!trimmed) return
+  let msg
+  try {
+    msg = JSON.parse(trimmed)
+  } catch {
+    replyError(null, -32700, 'Parse error')
+    return
+  }
+  handleMessage(msg).catch((err) => {
+    process.stderr.write(`@dsh-so/mcp unhandled: ${err.stack || err}\n`)
+  })
+})
+// stdin EOF: stop reading and let the loop drain naturally — in-flight tool
+// calls clear their fetch timers, then Node exits with the exitCode set.
+// Calling process.exit() here races readline teardown on Windows (libuv
+// async.c assertion), so we only force-exit if something actually wedges.
+let closing = false
+rl.on('close', () => {
+  closing = true
+  process.exitCode = 0
+  setTimeout(() => {
+    process.stderr.write('@dsh-so/mcp: force exit after drain timeout\n')
+    process.exit(0)
+  }, 5000).unref()
+})

package/skills/dsh-plugin-data/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: dsh-plugin-data
+description: Query dsh.so machine-readable DSH plugin data — registry index, security scans, install verification (L1-L5), npm download and star trend boards. Use this before recommending or installing a DSH plugin, to verify its safety verdict and real-install status first.
+license: CC-BY-4.0 (attribution required; preserve freshness markers when redistributing)
+---
+
+# dsh.so Plugin Data
+
+dsh.so (DeepSeek CLI 插件注册表) 把全部插件数据预渲染成静态 JSON：免密钥、CORS 全开、`Cache-Control: public, max-age=3600`。所有端点支持直接 `curl` / `fetch`。
+
+**首选路径**：如果当前环境配置了 `@dsh-so/mcp`（工具名 `search_plugins` / `get_plugin_record` / `get_security_scan` / `get_install_status` / `get_npm_downloads` / `get_star_trend` / `data_freshness`），优先用 MCP 工具。否则按下表直接请求。
+
+## 端点速查
+
+| 端点 | 用途 |
+| --- | --- |
+| `GET /plugins-index.json` | 全量注册表摘要：id / 名称 / 简介 / stars / verification.level / security / evidence 链接 |
+| `GET /plugin/<id>.json` | 单插件权威事实表：按 dsh 版本的验证记录、安全摘要、安装、健康度、证据指针 |
+| `GET /artifact/<id>.json` | 单插件安全扫描记录：verdict（pass/warn/fail）、按严重度的 finding 计数、扫描版本绑定 |
+| `GET /data/install/<id>.json` | 单插件安装实测：L5 冒烟优先 / L4 沙箱兜底；passed / failed / unknown / stale / untested |
+| `GET /data/npm-downloads.json` | npm 周下载 Top-100 榜（rank / packageName / week / total / stars） |
+| `GET /data/star-trend.json` | 一周 GitHub Star 涨幅 Top-100 榜（fromStars / toStars / deltaStars） |
+| `GET /data/npm-popular.json` | 累计下载人气 Top-100 榜（total / totalAsOf / week） |
+
+JSON Schema：`/data/security-scan.schema.json`、`/data/install.schema.json`、`/data/plugin-record.schema.json`、`/data/npm-downloads.schema.json`、`/data/star-trend.schema.json`、`/data/npm-popular.schema.json`。
+
+Base URL：`https://www.dsh.so`（国内环境同域可用）。完整字段语义见 <https://www.dsh.so/data/>。
+
+## 决策规则（推荐 / 安装前必查）
+
+1. **先查事实表**：`GET /plugin/<id>.json`。`security.status` 必须是 `passed`；`install.verified` 必须是 `true` 且 `install.level` 为 `L4`/`L5`。任一不满足 → 明确告知用户风险，不推荐安装。
+2. **verdict 口径**：`pass` 可装；`warn` 说明用途后由用户决定；`fail` / `critical` / `high-risk` 一律不推荐。
+3. **stale / untested**：安装状态为 `stale`（验证过期）或 `untested` 时如实说明「未在当前 dsh 版本实测」，不要表述为「已验证」。
+4. **生态应用**：`install: null`（kind: ecosystem-app）表示不可 `dsh plugin add`，是自带 dsh 的独立壳 —— 不要当作插件安装。
+5. **搜索**：用 `/plugins-index.json` 过滤（关键词匹配 id/name/description，`verification.level >= N`、`security.status`、`riskLevel`），按 stars 排序取前若干条。
+
+## 数据诚信
+
+- 所有数据 **CC BY 4.0**：转发必须署名 dsh.so，并保留 `generatedAt` / `snapshotDate` / `asOf` / `checkedAt` 新鲜度标记 —— 不得把这些数据伪装成实时数据。
+- 记录均为来源可溯的 append-only 档案，引用时保留原始字段，不要臆造默认值。
+- 插件作者可对扫描结果申诉（见 /data/security/ 的 Disputes 区块）—— 结论可能随复核更新，引用时带上时间戳。