@honlnk/picsense 0.1.0

package/dist/tools/analyze-images.js

@@ -0,0 +1,37 @@
+/**
+ * analyze_images 工具业务逻辑。
+ *
+ * 设计依据：docs/picsense-design.md §4.1、§4.2.5。
+ * - 输入 image_sources（URL/路径/base64 自动识别）+ prompt + 可选 session_id。
+ * - 无 session_id → 创建 session；有 → 追加一轮。
+ * - 返回 { session_id, summary, description }。
+ *
+ * 本函数是纯业务，不涉及 MCP 注册（那在 P5）。
+ */
+export class ToolInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ToolInputError';
+    }
+}
+/**
+ * 执行图片识别（支持多轮迭代）。
+ *
+ * 注意：首次调用时 image_sources 必填；传入已有 session_id 时，
+ * 沿用该 session 的图片，image_sources 会被忽略。
+ */
+export async function analyzeImages(manager, params) {
+    if (typeof params.prompt !== 'string' || params.prompt.trim() === '') {
+        throw new ToolInputError('prompt is required and must be a non-empty string.');
+    }
+    // 后续轮次（带 session_id）时，图片已在 session 内，不需要再传。
+    if (params.session_id) {
+        return manager.appendTurn(params.session_id, params.prompt);
+    }
+    // 首轮：必须有图片。
+    if (!Array.isArray(params.image_sources) || params.image_sources.length === 0) {
+        throw new ToolInputError('image_sources is required (with at least one image) when creating a new session.');
+    }
+    return manager.createSession(params.image_sources, params.prompt);
+}
+//# sourceMappingURL=analyze-images.js.map

package/dist/tools/analyze-images.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-images.js","sourceRoot":"","sources":["../../src/tools/analyze-images.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAgBH,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAAuB,EACvB,MAA2B;IAE3B,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACrE,MAAM,IAAI,cAAc,CAAC,oDAAoD,CAAC,CAAC;IACjF,CAAC;IAED,4CAA4C;IAC5C,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACtB,OAAO,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9D,CAAC;IAED,YAAY;IACZ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,MAAM,CAAC,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9E,MAAM,IAAI,cAAc,CACtB,kFAAkF,CACnF,CAAC;IACJ,CAAC;IAED,OAAO,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;AACpE,CAAC"}

package/dist/tools/analyze-video.js

@@ -0,0 +1,46 @@
+/**
+ * analyze_video 工具业务逻辑。
+ *
+ * 设计依据：docs/picsense-design.md §4.1、§4.3。
+ *
+ * 视频是独立输入形态，与图片并列。由于项目默认 provider（OpenAI Responses API）
+ * 原生不支持视频，本工具通过抽帧把视频转成帧序列，复用图片管线发送给视觉模型。
+ *
+ * - 输入 video_source（URL/本地路径）+ prompt + 可选 session_id。
+ * - 无 session_id → 抽帧创建 session；有 → 追加一轮（复用现有 appendTurn）。
+ * - 返回 { session_id, summary, description }，与 analyze_images 一致。
+ *
+ * 抽帧在首轮一次性完成，后续轮次复用 session（帧作为首轮图片已挂载），
+ * 不会重复抽帧——这与 SessionManager 的设计一致（图片只挂首轮）。
+ */
+import { loadVideo, VideoLoadError } from '../core/video-loader.js';
+// 复用 analyze-images 的输入校验错误类型，保持一致语义。
+import { ToolInputError } from './analyze-images.js';
+export { VideoLoadError };
+/**
+ * 执行视频识别（支持多轮迭代）。
+ *
+ * @param manager Session 管理器。
+ * @param params 工具参数。
+ * @param maxVideoBytes 单个视频字节上限。
+ * @param frameOpts 抽帧选项（fps / maxFrames）。
+ */
+export async function analyzeVideo(manager, params, maxVideoBytes, frameOpts) {
+    if (typeof params.prompt !== 'string' || params.prompt.trim() === '') {
+        throw new ToolInputError('prompt is required and must be a non-empty string.');
+    }
+    // 后续轮次（带 session_id）时，视频帧已在 session 内，无需再抽帧。
+    if (params.session_id) {
+        return manager.appendTurn(params.session_id, params.prompt);
+    }
+    // 首轮：必须有视频源。
+    if (typeof params.video_source !== 'string' || params.video_source.trim() === '') {
+        throw new ToolInputError('video_source is required when creating a new session.');
+    }
+    // 抽帧。
+    const video = await loadVideo(params.video_source, maxVideoBytes, frameOpts);
+    // 用抽出的帧创建 session（复用 createSessionWithImages，帧已加载无需再加载）。
+    // displaySources 用原始视频引用（URL/路径），避免巨大的 base64 占用 list_sessions 展示。
+    return manager.createSessionWithImages(video.frames, [video.source], params.prompt);
+}
+//# sourceMappingURL=analyze-video.js.map

package/dist/tools/analyze-video.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-video.js","sourceRoot":"","sources":["../../src/tools/analyze-video.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,SAAS,EAAqB,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACvF,sCAAsC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAcrD,OAAO,EAAE,cAAc,EAAE,CAAC;AAE1B;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAuB,EACvB,MAA0B,EAC1B,aAAqB,EACrB,SAAuB;IAEvB,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACrE,MAAM,IAAI,cAAc,CAAC,oDAAoD,CAAC,CAAC;IACjF,CAAC;IAED,6CAA6C;IAC7C,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACtB,OAAO,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9D,CAAC;IAED,aAAa;IACb,IAAI,OAAO,MAAM,CAAC,YAAY,KAAK,QAAQ,IAAI,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACjF,MAAM,IAAI,cAAc,CAAC,uDAAuD,CAAC,CAAC;IACpF,CAAC;IAED,MAAM;IACN,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,MAAM,CAAC,YAAY,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC;IAE7E,yDAAyD;IACzD,mEAAmE;IACnE,OAAO,OAAO,CAAC,uBAAuB,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;AACtF,CAAC"}

package/dist/tools/list-sessions.js

@@ -0,0 +1,11 @@
+/**
+ * list_sessions 工具业务逻辑。
+ *
+ * 设计依据：docs/picsense-design.md §4.1、§4.2.5。
+ * 返回当前所有 session 的列表（含简介、关联图片、迭代轮数、最后访问时间）。
+ * 截断显示已由 SessionManager.toSnapshot 完成。
+ */
+export async function listSessions(manager) {
+    return { sessions: manager.listSessions() };
+}
+//# sourceMappingURL=list-sessions.js.map

package/dist/tools/list-sessions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-sessions.js","sourceRoot":"","sources":["../../src/tools/list-sessions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAAuB;IACxD,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC;AAC9C,CAAC"}

package/dist/utils/config.js

@@ -0,0 +1,88 @@
+/**
+ * 环境变量配置管理。
+ *
+ * 设计依据：docs/picsense-design.md §6.2 —— 全部配置走环境变量，代码内零硬编码。
+ * 缺失必填项时抛出清晰错误，便于用户在 stdio 启动时第一时间发现问题。
+ */
+const ONE_MB = 1024 * 1024;
+const ONE_HOUR = 60 * 60 * 1000;
+const SUPPORTED_PROVIDERS = ['openai', 'qwen', 'kimi'];
+function isProviderName(value) {
+    return SUPPORTED_PROVIDERS.includes(value);
+}
+function readProvider(name, env) {
+    const prefix = name.toUpperCase();
+    const apiKey = env[`${prefix}_API_KEY`];
+    const model = env[`${prefix}_MODEL`];
+    const baseUrl = env[`${prefix}_BASE_URL`];
+    // 没 Key 视为该 provider 未启用。
+    if (!apiKey)
+        return undefined;
+    if (!model) {
+        throw new ConfigError(`${prefix}_MODEL is required when ${prefix}_API_KEY is set.`);
+    }
+    return { name, apiKey, model, baseUrl };
+}
+/**
+ * 加载并校验配置。必填项缺失时抛 ConfigError。
+ *
+ * @param env 可注入环境变量，默认读 process.env，便于测试。
+ */
+export function loadConfig(env = process.env) {
+    const defaultProviderRaw = env['DEFAULT_PROVIDER'] ?? 'openai';
+    if (!isProviderName(defaultProviderRaw)) {
+        throw new ConfigError(`DEFAULT_PROVIDER="${defaultProviderRaw}" is not supported. Supported: ${SUPPORTED_PROVIDERS.join(', ')}.`);
+    }
+    const defaultProvider = defaultProviderRaw;
+    const providers = {
+        openai: readProvider('openai', env),
+        qwen: readProvider('qwen', env),
+        kimi: readProvider('kimi', env),
+    };
+    // 默认 provider 必须可用（已配置 Key）。
+    if (!providers[defaultProvider]) {
+        const prefix = defaultProvider.toUpperCase();
+        throw new ConfigError(`Default provider "${defaultProvider}" is not configured. ` +
+            `Please set ${prefix}_API_KEY and ${prefix}_MODEL (see .env.example).`);
+    }
+    const maxImageMb = Number(env['MAX_IMAGE_MB'] ?? '5');
+    if (!Number.isFinite(maxImageMb) || maxImageMb <= 0) {
+        throw new ConfigError(`MAX_IMAGE_MB="${env['MAX_IMAGE_MB']}" is not a positive number.`);
+    }
+    const timeoutMs = Number(env['TIMEOUT_MS'] ?? '300000');
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw new ConfigError(`TIMEOUT_MS="${env['TIMEOUT_MS']}" is not a positive number.`);
+    }
+    // 视频配置（可选，均有默认值）。
+    const maxVideoMb = Number(env['MAX_VIDEO_MB'] ?? '100');
+    if (!Number.isFinite(maxVideoMb) || maxVideoMb <= 0) {
+        throw new ConfigError(`MAX_VIDEO_MB="${env['MAX_VIDEO_MB']}" is not a positive number.`);
+    }
+    const videoMaxFrames = Number(env['VIDEO_MAX_FRAMES'] ?? '30');
+    if (!Number.isFinite(videoMaxFrames) || videoMaxFrames <= 0) {
+        throw new ConfigError(`VIDEO_MAX_FRAMES="${env['VIDEO_MAX_FRAMES']}" is not a positive number.`);
+    }
+    const videoFps = Number(env['VIDEO_FPS'] ?? '1');
+    if (!Number.isFinite(videoFps) || videoFps <= 0) {
+        throw new ConfigError(`VIDEO_FPS="${env['VIDEO_FPS']}" is not a positive number.`);
+    }
+    return {
+        defaultProvider,
+        providers,
+        maxImageBytes: Math.floor(maxImageMb * ONE_MB),
+        maxVideoBytes: Math.floor(maxVideoMb * ONE_MB),
+        videoMaxFrames: Math.floor(videoMaxFrames),
+        videoFps,
+        timeoutMs,
+        sessionTtlMs: 24 * ONE_HOUR,
+        sessionCleanupIntervalMs: ONE_HOUR,
+    };
+}
+/** 配置错误，携带面向用户的提示信息。 */
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigError';
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/utils/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/utils/config.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@honlnk/picsense",
+  "version": "0.1.0",
+  "description": "A local MCP server that gives unimodal LLMs multimodal vision — image/video recognition with multi-turn iterative analysis.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": "honlnk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/honlnk/picsense.git"
+  },
+  "homepage": "https://github.com/honlnk/picsense#readme",
+  "bugs": {
+    "url": "https://github.com/honlnk/picsense/issues"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "claude",
+    "vision",
+    "image-recognition",
+    "video-recognition",
+    "multimodal",
+    "llm-tools",
+    "ai-tools"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "picsense": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').chmodSync('dist/index.js', 0o755)\"",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "smoke": "tsx scripts/smoke.ts",
+    "smoke:session": "tsx scripts/smoke-session.ts",
+    "smoke:tools": "tsx scripts/smoke-tools.ts",
+    "smoke:video": "tsx scripts/smoke-video.ts",
+    "e2e": "pnpm build && tsx scripts/e2e-client.ts",
+    "sim": "pnpm build && tsx scripts/zcode-sim.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm run typecheck"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "ffmpeg-static": "^5.3.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": ["ffmpeg-static"]
+  }
+}