asset-mcp 0.2.1 → 0.2.9

package/README.md

@@ -1,94 +1,63 @@
 # asset-mcp
 
-给 Cursor 使用的 MCP Server（OAuth 标准流程骨架，零依赖版本）。
+在 Cursor 等支持 MCP 的 IDE 中连接资产管理平台（OAuth2 设备码登录；bundle 打 zip 依赖 `jszip`）。
 
 ## 功能
 
-- 暴露认证工具：`mcp_auth`（`methods/start/poll/status/logout`，仅 OAuth2 设备码）
-- 暴露身份工具：`auth.me`
-- 暴露查询工具：`assets.search`
-- 暴露业务工具：`assets.create`
-- 写操作权限由后端统一拦截（scope + RBAC + 资源级权限）
+- `mcp_auth`：`methods` / `start` / `poll` / `status` / `logout`（OAuth2 设备码）
+- `auth_me`：当前用户
+- `assets_search`：查询资产列表
+- `assets_detail`：按 ID 查单条详情（须指定类型；能否查看由后端判定）
+- `assets_download`：按 ID 将资产写入**本工程工作区**（须配置 `ASSET_MCP_WORKSPACE_ROOT`；鉴权同详情）
+- `assets_create`：创建资产（权限由后端拦截）
 
-## 运行
+## 使用
 
 ```bash
-cd asset-mcp
-npm start
+npx -y asset-mcp@latest
 ```
 
-## 作为 npm 包使用
-
-```bash
-npx -y asset-mcp
-```
-
-## 发布到 npm
-
-```bash
-npm login
-npm publish --access public
-```
-
-> 如果包名已被占用，请先修改 `package.json` 里的 `name`（例如加组织作用域）。
-
-## 在 Cursor 中配置（示例）
-
-将 MCP 命令配置为：
-
-```bash
-npx -y asset-mcp
-```
+在 Cursor 的 MCP 配置里将启动命令设为上述命令，并配置下方环境变量。
 
 ## 环境变量
 
 ```bash
 export ASSET_MCP_BASE_URL="http://localhost:8080"
-export ASSET_MCP_CLIENT_ID="asset-mcp"
-export ASSET_MCP_SCOPES="assets.read assets.write"
+# 下载到本工程目录时必填（Cursor MCP 里可用 ${workspaceFolder}）
+export ASSET_MCP_WORKSPACE_ROOT="/你的工程根路径"
 ```
 
-可选项：
-
-- `ASSET_MCP_DEVICE_CODE_PATH`（默认 `/oauth/device/code`）
-- `ASSET_MCP_TOKEN_PATH`（默认 `/oauth/token`）
-- `ASSET_MCP_REVOKE_PATH`（默认 `/oauth/revoke`）
-
-## 标准授权流程（Device Code）
+## 登录（设备码）
 
-1. 先调用 `mcp_auth`，参数：`{ "action": "start" }`
-2. 按返回的 `verificationUri + userCode` 去浏览器授权
-3. 再调用 `mcp_auth`，参数：`{ "action": "poll" }`
-4. 成功后用 `auth.me` 验证登录身份
-5. 然后可调用 `assets.create`
+1. 调用 `mcp_auth`，`{ "action": "start" }`
+2. 在浏览器打开返回的 `verificationUri`，按提示完成授权（可配合 `userCode`）
+3. 调用 `mcp_auth`，`{ "action": "poll" }`
+4. 使用 `auth_me` 确认已登录
 
-可选先调 `mcp_auth`：`{ "action": "methods" }` 查看步骤说明。
+可先调用 `{ "action": "methods" }` 查看说明。请在浏览器中登录，**不要**在对话里向 MCP 发送密码。
 
-说明：登录**仅**走 OAuth2 设备码；用户在浏览器授权页输入账号密码，**不要**通过 MCP 传密码。
+## `assets_search`
 
-## 工具入参（assets.search）
+- `assetType`：`rule` | `skill` | `mcp` | `all`（默认 `all`）
+- `keyword`：关键词，透传后端，与平台搜索一致；固定第 1 页，每类最多 10 条；`all` 时每类各最多 10 条
 
-- `assetType`: `"rule" | "skill" | "mcp" | "all"`（默认 `all`）
-- `keyword`: 关键词
+## `assets_detail`
 
-说明：
+- `assetType`：`rule` | `skill` | `mcp`（必填）
+- `id`：资产 ID（必填，正整数）
 
-- 查询条件只保留 `assetType + keyword`
-- `keyword` 直接透传平台后端，因此搜索逻辑与平台当前页面一致
-- 不开放分页参数，固定查询第 1 页、每类最多 10 条
-- `assetType=all` 时：`rule/skill/mcp` 各返回最多 10 条
+无查看权限或资源不存在时，接口会失败；与 Web 端一致，由后端统一鉴权。
 
-## 工具入参（assets.create）
+## `assets_download`
 
-- `assetType`: `"rule" | "skill" | "mcp"`
-- `name`: 资产名称
-- `description`: 资产描述
-- `version`: 可选，默认 `v1.0`
-- `changeLog`: 可选，默认 `初始创建`
-- `content`: 可选（rule/skill）
-- `mcpType/configJson/toolsJson/remark`: 可选（mcp）
+- `assetType`、`id`：同 `assets_detail`（无权限则无法拉取内容）
+- `asZip`：可选，**rule/skill 且为 bundle** 时设为 `true` 则只生成一个 `.zip`，不写展开目录
+- `relativeDir`：可选，表示 **`.cursor` 下面的子路径**（不要带 `.cursor` 前缀）；默认空，即直接 `{工作区}/.cursor/rules|skills|mcps/{资产名}/`
+- **rule / skill**：无 ASSET_BUNDLE 时为单个 `.md`；有 bundle 时默认展开为多文件目录；传 **`asZip: true`** 时为单个 `.zip`（与 Web 端 zip 一致，例：`.cursor/rules/测试.zip`）
+- **mcp**：写入 `config.json`、`tools.json`、`meta.md`
 
-## 说明
+## `assets_create`
 
-- token 存储在用户目录 `~/.asset-mcp/tokens.json`
-- 建议上线时切换到系统钥匙串存储（如 macOS Keychain）
+- `assetType`：`rule` | `skill` | `mcp`
+- `name`、`description`：必填（按后端校验）
+- `version`、`changeLog`、`content`（rule/skill）、`mcpType` / `configJson` / `toolsJson` / `remark`（mcp）等见平台接口约定

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "asset-mcp",
-  "version": "0.2.1",
+  "version": "0.2.9",
   "license": "MIT",
   "description": "MCP server for asset operations in Cursor",
   "type": "module",
@@ -16,12 +16,15 @@
   ],
   "scripts": {
     "start": "node src/server.js",
-    "check": "node --check src/server.js",
+    "check": "node --check src/server.js && node --check src/backend.js && node --check src/download-asset.js && node --check src/asset-bundle.js",
     "prepublishOnly": "npm run check"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },
+  "dependencies": {
+    "jszip": "^3.10.1"
+  },
   "engines": {
     "node": ">=18"
   },

package/src/asset-bundle.js

@@ -0,0 +1,52 @@
+/**
+ * 与前端 assetBundle.ts 对齐：解析正文中的 ASSET_BUNDLE_V1 块。
+ */
+
+const MARKER_REGEX = /<!--\s*ASSET_BUNDLE_V1:([A-Za-z0-9+/=]+)\s*-->/
+
+export function parseAssetBundle(raw, defaultEntryPath = 'ENTRY') {
+  const source = raw ?? ''
+  const match = source.match(MARKER_REGEX)
+  if (!match) {
+    return {
+      entryContent: source,
+      files: [],
+      folders: [],
+      entryPath: defaultEntryPath,
+      bundled: false,
+    }
+  }
+
+  const marker = match[0]
+  const entryContent = source.replace(marker, '').trimEnd()
+  try {
+    const decoded = Buffer.from(match[1], 'base64').toString('utf8')
+    const payload = JSON.parse(decoded)
+    const files = Array.isArray(payload.files)
+      ? payload.files
+          .filter(f => f && typeof f.path === 'string')
+          .map(f => ({ path: f.path, content: String(f.content ?? '') }))
+      : []
+    const folders = Array.isArray(payload.folders)
+      ? payload.folders.filter(f => typeof f === 'string').map(f => f.trim()).filter(Boolean)
+      : []
+    if (!files.length) {
+      return { entryContent, files: [], folders, entryPath: defaultEntryPath, bundled: false }
+    }
+    return {
+      entryContent,
+      files,
+      folders,
+      entryPath: payload.entryPath || files[0].path || defaultEntryPath,
+      bundled: true,
+    }
+  } catch {
+    return {
+      entryContent,
+      files: [],
+      folders: [],
+      entryPath: defaultEntryPath,
+      bundled: false,
+    }
+  }
+}

package/src/backend.js

@@ -88,6 +88,27 @@ export async function whoAmI() {
   return requestWithToken(config.api.mePath, { method: 'GET' })
 }
 
+function parsePositiveId(raw) {
+  const n = typeof raw === 'string' ? parseInt(raw, 10) : Number(raw)
+  if (!Number.isFinite(n) || n < 1 || !Number.isInteger(n)) {
+    throw new Error('id 须为正整数')
+  }
+  return n
+}
+
+/**
+ * 单条详情：走平台 GET /api/v1/assets/{type}/{id}，可见性与角色由后端 SQL + 业务校验，无权限时 404/业务错误。
+ */
+export async function getAssetDetail(args = {}) {
+  const assetType = args.assetType
+  if (!['rule', 'skill', 'mcp'].includes(assetType)) {
+    throw new Error('assetType 须为 rule、skill 或 mcp')
+  }
+  const id = parsePositiveId(args.id)
+  const path = config.api.assetDetailPath(assetType, id)
+  return requestWithToken(path, { method: 'GET' })
+}
+
 export async function searchAssets(args = {}) {
   const assetType = args.assetType || 'all'
   const query = buildAssetListQuery(args)

package/src/config.js

@@ -26,6 +26,8 @@ export const config = {
     authLogoutPath: '/api/v1/auth/logout',
     /** 统一资产：GET 列表 / POST 创建，路径变量为 rule | skill | mcp */
     assetsPath: (assetType) => `/api/v1/assets/${assetType}`,
+    /** 单条详情：GET，权限由后端校验 */
+    assetDetailPath: (assetType, id) => `/api/v1/assets/${assetType}/${id}`,
     /** 跨类型列表（query 可带 assetType / keyword / mine 等） */
     assetsMarketPath: '/api/v1/assets',
     mePath: '/api/v1/auth/me',

package/src/download-asset.js

@@ -0,0 +1,168 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import JSZip from 'jszip'
+import { parseAssetBundle } from './asset-bundle.js'
+
+function sanitizeFilename(name, fallback) {
+  const normalized = String(name ?? '').trim().replace(/[\\/:*?"<>|]+/g, '-')
+  return normalized || fallback
+}
+
+function normalizeExportPath(filePath, entryPath) {
+  if (filePath !== entryPath) return filePath
+  const slashIdx = filePath.lastIndexOf('/')
+  const dotIdx = filePath.lastIndexOf('.')
+  const hasExt = dotIdx > slashIdx
+  return hasExt ? filePath : `${filePath}.md`
+}
+
+function assertUnderRoot(rootDir, absPath) {
+  const root = path.resolve(rootDir)
+  const abs = path.resolve(absPath)
+  const rel = path.relative(root, abs)
+  if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new Error('路径超出 ASSET_MCP_WORKSPACE_ROOT，拒绝写入')
+  }
+}
+
+/** 将相对路径拆成安全段，禁止 .. */
+function splitSafeRel(rel) {
+  return String(rel ?? '')
+    .split(/[/\\]+/)
+    .map(s => s.trim())
+    .filter(Boolean)
+    .map(seg => {
+      if (seg === '..' || seg === '.') throw new Error('非法相对路径')
+      if (seg.includes('/') || seg.includes('\\')) throw new Error('非法路径段')
+      return seg
+    })
+}
+
+function resolveUnderRoot(rootDir, ...segments) {
+  let cur = path.resolve(rootDir)
+  for (const seg of segments) {
+    if (!seg) continue
+    cur = path.join(cur, seg)
+    assertUnderRoot(rootDir, cur)
+  }
+  return cur
+}
+
+function buildMcpMeta(asset) {
+  const lines = [
+    `# ${asset.name ?? 'MCP'}`,
+    '',
+    asset.description ? `## 简介\n\n${asset.description}\n` : '',
+    asset.remark ? `## 备注\n\n${asset.remark}\n` : '',
+    `版本: ${asset.version ?? '-'}`,
+    `类型: ${asset.type ?? '-'}`,
+  ]
+  return lines.filter(Boolean).join('\n')
+}
+
+function safeFileRel(rel) {
+  return String(rel)
+    .split(/[/\\]+/)
+    .map(s => s.trim())
+    .filter(Boolean)
+    .map(seg => {
+      if (seg === '..' || seg === '.') throw new Error('非法文件路径')
+      return seg
+    })
+}
+
+/** 与工程习惯一致：规则 → rules，技能 → skills，MCP → mcps */
+function typeFolder(assetType) {
+  if (assetType === 'rule') return 'rules'
+  if (assetType === 'skill') return 'skills'
+  if (assetType === 'mcp') return 'mcps'
+  throw new Error(`不支持的 assetType: ${assetType}`)
+}
+
+/**
+ * 将资产详情写入工作区目录（与前端导出语义接近）。
+ * @param {{ asZip?: boolean }} [options] rule/skill 且为 bundle 时，asZip=true 生成单个 zip（与 Web 端 zip 导出一致）
+ * @returns {{ paths: string[], rootDir: string, format: string }}
+ */
+export async function exportAssetToWorkspace(asset, workspaceRoot, relativeDir, options = {}) {
+  const asZip = Boolean(options.asZip)
+  const root = path.resolve(workspaceRoot.trim())
+  assertUnderRoot(root, root)
+
+  /** 固定落在工作区 `.cursor/` 下；relativeDir 为其下的可选子目录（多级用 /） */
+  let dirParts = splitSafeRel(relativeDir ?? '')
+
+  const assetType = asset.assetType
+  const baseName = sanitizeFilename(asset.name, `${assetType}-${asset.id}`)
+  const tf = typeFolder(assetType)
+  const destRoot = resolveUnderRoot(root, '.cursor', ...dirParts, tf, baseName)
+
+  if (assetType === 'rule' || assetType === 'skill') {
+    const defaultEntry = assetType === 'rule' ? 'RULE' : 'SKILL'
+    const content = asset.content ?? ''
+    const parsed = parseAssetBundle(content, defaultEntry)
+
+    if (parsed.bundled && asZip) {
+      const zip = new JSZip()
+      for (const folder of parsed.folders) {
+        if (folder.trim()) zip.folder(folder)
+      }
+      for (const file of parsed.files) {
+        if (!file.path.trim()) continue
+        const rel = normalizeExportPath(file.path, parsed.entryPath)
+        zip.file(rel, file.content ?? '')
+      }
+      const buf = await zip.generateAsync({ type: 'nodebuffer' })
+      const zipPath = resolveUnderRoot(root, '.cursor', ...dirParts, tf, `${baseName}.zip`)
+      await fs.mkdir(path.dirname(zipPath), { recursive: true })
+      await fs.writeFile(zipPath, buf)
+      const parent = path.dirname(zipPath)
+      return { paths: [zipPath], rootDir: parent, format: 'bundle-zip' }
+    }
+
+    await fs.mkdir(destRoot, { recursive: true })
+
+    if (!parsed.bundled) {
+      const filePath = resolveUnderRoot(root, '.cursor', ...dirParts, tf, baseName, `${baseName}.md`)
+      await fs.writeFile(filePath, content, 'utf8')
+      return { paths: [filePath], rootDir: destRoot, format: 'single-markdown' }
+    }
+
+    for (const folder of parsed.folders) {
+      if (!folder.trim()) continue
+      const parts = safeFileRel(folder)
+      const dir = resolveUnderRoot(root, '.cursor', ...dirParts, tf, baseName, ...parts)
+      await fs.mkdir(dir, { recursive: true })
+    }
+
+    const written = []
+    for (const file of parsed.files) {
+      if (!file.path.trim()) continue
+      const rel = normalizeExportPath(file.path, parsed.entryPath)
+      const fparts = safeFileRel(rel)
+      const filePath = resolveUnderRoot(root, '.cursor', ...dirParts, tf, baseName, ...fparts)
+      await fs.mkdir(path.dirname(filePath), { recursive: true })
+      await fs.writeFile(filePath, file.content ?? '', 'utf8')
+      written.push(filePath)
+    }
+
+    return { paths: written, rootDir: destRoot, format: 'bundle' }
+  }
+
+  if (assetType === 'mcp') {
+    await fs.mkdir(destRoot, { recursive: true })
+    const paths = []
+    const p1 = resolveUnderRoot(root, '.cursor', ...dirParts, tf, baseName, 'config.json')
+    const p2 = resolveUnderRoot(root, '.cursor', ...dirParts, tf, baseName, 'tools.json')
+    const p3 = resolveUnderRoot(root, '.cursor', ...dirParts, tf, baseName, 'meta.md')
+    await fs.writeFile(p1, asset.configJson ?? '{}', 'utf8')
+    paths.push(p1)
+    await fs.writeFile(p2, asset.toolsJson ?? '[]', 'utf8')
+    paths.push(p2)
+    await fs.writeFile(p3, buildMcpMeta(asset), 'utf8')
+    paths.push(p3)
+    return { paths, rootDir: destRoot, format: 'mcp-json' }
+  }
+
+  throw new Error(`不支持的 assetType: ${assetType}`)
+}

package/src/server.js

@@ -1,5 +1,6 @@
 import readline from 'node:readline'
-import { createAsset, searchAssets, whoAmI } from './backend.js'
+import { createAsset, getAssetDetail, searchAssets, whoAmI } from './backend.js'
+import { exportAssetToWorkspace } from './download-asset.js'
 import { readTokens } from './token-store.js'
 import { pollDeviceToken, revokeAndClearTokens, startDeviceAuthorization } from './oauth.js'
 
@@ -23,7 +24,7 @@ const TOOL_DEFS = [
     },
   },
   {
-    name: 'auth.me',
+    name: 'auth_me',
     description: '查看当前登录用户信息',
     inputSchema: {
       type: 'object',
@@ -32,9 +33,9 @@ const TOOL_DEFS = [
     },
   },
   {
-    name: 'assets.search',
+    name: 'assets_search',
     description:
-      '查询资产（rule/skill/mcp/all），GET /api/v1/assets/{assetType}；固定每类最多 10 条（第 1 页），无分页参数',
+      '查询资产（rule/skill/mcp/all），GET /api/v1/assets/{assetType}；固定每类最多 10 条（第 1 页），无分页参数。若用户只说「查询资产」等而未给出筛选条件，助手应先询问需要哪些条件，并列出可选：assetType、keyword、mine、status、categoryId/categoryIds、type（仅 mcp：local/remote）；用户补充或确认后再调用。',
     inputSchema: {
       type: 'object',
       properties: {
@@ -50,7 +51,42 @@ const TOOL_DEFS = [
     },
   },
   {
-    name: 'assets.create',
+    name: 'assets_detail',
+    description:
+      '按 ID 查询单条资产详情（须指定 assetType）。能否查看由后端按当前用户、资产状态与可见范围判定；无权限或不存在时返回错误。MCP 仅转发请求，无法在客户端绕过权限。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        assetType: { type: 'string', enum: ['rule', 'skill', 'mcp'] },
+        id: { type: 'integer', minimum: 1, description: '资产主键 ID' },
+      },
+      required: ['assetType', 'id'],
+    },
+  },
+  {
+    name: 'assets_download',
+    description:
+      '按 ID 将资产下载到本机工作区 .cursor 目录下：先走与详情相同的接口鉴权，再写入文件。须设置 ASSET_MCP_WORKSPACE_ROOT。路径为 .cursor/{可选子目录}/rules|skills|mcps/。rule/skill：无 bundle 为单 .md；有 bundle 时默认展开为文件夹，若 asZip=true 则打成一个 .zip（与 Web 导出 zip 一致）；mcp 为 config.json、tools.json、meta.md。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        assetType: { type: 'string', enum: ['rule', 'skill', 'mcp'] },
+        id: { type: 'integer', minimum: 1, description: '资产主键 ID' },
+        relativeDir: {
+          type: 'string',
+          description: '位于 .cursor 下的可选子目录，如 imported 或 backup/2026（不要写 .cursor 前缀），默认空即直接写在 .cursor/rules 等下',
+        },
+        asZip: {
+          type: 'boolean',
+          description:
+            '仅 rule/skill 且正文为 ASSET_BUNDLE 时有效：true 时生成单个 .zip（如 .cursor/rules/名称.zip），false 为展开目录（默认）',
+        },
+      },
+      required: ['assetType', 'id'],
+    },
+  },
+  {
+    name: 'assets_create',
     description: '创建资产（权限最终由后端拦截）',
     inputSchema: {
       type: 'object',
@@ -103,7 +139,7 @@ function authMethodsPayload() {
       '① mcp_auth action=start → 取得 userCode、verificationUri（或 verificationUriComplete）',
       '② 用户在浏览器打开链接，完成授权（若页面要求输入用户码，使用返回的 userCode）',
       '③ mcp_auth action=poll → 换取 access_token 并写入本地凭证',
-      '④ 可选：auth.me 或 mcp_auth action=status 校验',
+      '④ 可选：auth_me 或 mcp_auth action=status 校验',
     ],
     hint: '用户可说「我要登录资产管理平台」。勿使用账号密码调用 MCP；账号密码仅在浏览器授权页由用户自行输入。',
   }
@@ -210,11 +246,44 @@ async function handleAssetsSearch(args = {}) {
   })
 }
 
+async function handleAssetsDetail(args = {}) {
+  const data = await getAssetDetail(args)
+  return makeTextResult({
+    ok: true,
+    message: '查询成功',
+    data,
+  })
+}
+
+async function handleAssetsDownload(args = {}) {
+  const workspaceRoot = process.env.ASSET_MCP_WORKSPACE_ROOT?.trim()
+  if (!workspaceRoot) {
+    throw new Error(
+      '未设置 ASSET_MCP_WORKSPACE_ROOT。请在 MCP 的 env 中配置为当前工程根目录，例如：ASSET_MCP_WORKSPACE_ROOT = ${workspaceFolder}（Cursor 会展开变量）。'
+    )
+  }
+  const asset = await getAssetDetail(args)
+  const merged = { ...asset, assetType: asset.assetType ?? args.assetType }
+  const out = await exportAssetToWorkspace(merged, workspaceRoot, args.relativeDir, {
+    asZip: Boolean(args.asZip),
+  })
+  return makeTextResult({
+    ok: true,
+    message: '已写入工作区',
+    workspaceRoot,
+    relativeDir: args.relativeDir ?? '',
+    underCursor: true,
+    ...out,
+  })
+}
+
 async function handleToolCall(name, args) {
   if (name === 'mcp_auth') return handleAuthTool(args)
-  if (name === 'auth.me') return makeTextResult(await whoAmI())
-  if (name === 'assets.search') return handleAssetsSearch(args)
-  if (name === 'assets.create') return handleAssetsCreate(args)
+  if (name === 'auth_me' || name === 'auth.me') return makeTextResult(await whoAmI())
+  if (name === 'assets_search' || name === 'assets.search') return handleAssetsSearch(args)
+  if (name === 'assets_detail' || name === 'assets.detail') return handleAssetsDetail(args)
+  if (name === 'assets_download' || name === 'assets.download') return handleAssetsDownload(args)
+  if (name === 'assets_create' || name === 'assets.create') return handleAssetsCreate(args)
   throw new Error(`未知工具: ${name}`)
 }
 
@@ -225,7 +294,7 @@ async function handleRequest(req) {
     return ok(id, {
       protocolVersion: '2024-11-05',
       capabilities: { tools: {} },
-      serverInfo: { name: 'asset-mcp', version: '0.2.0' },
+      serverInfo: { name: 'asset-mcp', version: '0.2.9' },
     })
   }