@urovotest/urovosdk-docs-mcp 1.0.1

package/docs/source/kiosk_lock_task.md

@@ -0,0 +1,86 @@
+# Kiosk / Lock Task Mode
+
+**DISCOVERED**: These APIs exist in `DeviceManager` and are used in the demo (`SystemActivity.java`), but are NOT documented in the official SDK reference docs. Found by searching demo source code.
+
+## DeviceManager / setLockTaskMode
+
+- **Package/class**: `com.urovo.device.DeviceManager`
+- **Demo reference**: `assets/UrovoPosSdkDemo/.../view/SystemActivity.java` (lines 142-148)
+
+### Purpose
+Enable or disable Android Lock Task Mode (kiosk mode) for a specific app package. When enabled, the user is locked to the specified app — cannot press Home, Recent Apps, or swipe away. Navigation bar is hidden/disabled. Power button short-press is suppressed.
+
+### Signature
+```java
+void setLockTaskMode(String packageName, boolean lock)
+```
+
+### Parameters
+| Name | Type | Description |
+|---|---|---|
+| packageName | String | The package name of the app to lock/unlock (use `getPackageName()`) |
+| lock | boolean | `true` to enable lock task mode, `false` to disable |
+
+### Example
+```java
+// Enable kiosk mode before transaction
+new DeviceManager().setLockTaskMode(getPackageName(), true);
+
+// Disable kiosk mode after transaction
+new DeviceManager().setLockTaskMode(getPackageName(), false);
+```
+
+---
+
+## DeviceManager / setLockTaskModePassword
+
+- **Package/class**: `com.urovo.device.DeviceManager`
+- **Demo reference**: `assets/UrovoPosSdkDemo/.../view/SystemActivity.java` (line 144)
+
+### Purpose
+Set the password required to exit Lock Task Mode. Should be called together with `setLockTaskMode(packageName, true)`.
+
+### Signature
+```java
+void setLockTaskModePassword(String password)
+```
+
+### Parameters
+| Name | Type | Description |
+|---|---|---|
+| password | String | Password to unlock/exit kiosk mode (e.g., "123456") |
+
+### Example
+```java
+new DeviceManager().setLockTaskMode(getPackageName(), true);
+new DeviceManager().setLockTaskModePassword("123456");
+```
+
+---
+
+## Recommended Pattern for Payment Apps
+
+```java
+// Transaction starts — lock user to payment app
+new DeviceManager().setLockTaskMode(getPackageName(), true);
+new DeviceManager().setLockTaskModePassword("123456");
+
+// Optional: also hide status bar for cleaner UI
+View decorView = getWindow().getDecorView();
+decorView.setSystemUiVisibility(
+    View.SYSTEM_UI_FLAG_IMMERSIVE_STICKY
+    | View.SYSTEM_UI_FLAG_HIDE_NAVIGATION
+    | View.SYSTEM_UI_FLAG_FULLSCREEN
+    | View.SYSTEM_UI_FLAG_LAYOUT_STABLE
+    | View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN
+    | View.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION
+);
+
+// Transaction ends (success, cancel, or error) — unlock
+new DeviceManager().setLockTaskMode(getPackageName(), false);
+```
+
+## Related APIs (documented elsewhere)
+
+- `SystemProviderImpl.setLockScreenNon()` — disable screen lock entirely (documented in general_sdk.md section 12.3)
+- `BaseActivity.fullScreen()` — standard Android fullscreen helper (demo code)

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@urovotest/urovosdk-docs-mcp",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "1.0.1",
+  "description": "UrovoSDK documentation MCP server (stdio, bundled docs — npx ready)",
+  "type": "module",
+  "main": "src/launch.js",
+  "bin": {
+    "urovosdk-docs-mcp": "src/launch.js"
+  },
+  "files": [
+    "src",
+    "docs"
+  ],
+  "scripts": {
+    "bundle": "node scripts/bundle.js",
+    "prepack": "node scripts/bundle.js",
+    "verify": "node scripts/verify.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "urovosdk",
+    "urovo",
+    "pos"
+  ],
+  "license": "UNLICENSED",
+  "private": false
+}

package/src/launch.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * UrovoSDK Docs MCP 入口：每次启动检查 npm 最新版并同步，再启动 stdio 服务
+ */
+import { readFileSync } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { ensureLatestFromRegistry } from "./lib/check-update.js";
+import { startMcpServer } from "./server.js";
+
+const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const PACKAGE_NAME = JSON.parse(
+  readFileSync(path.join(pkgRoot, "package.json"), "utf-8")
+).name;
+
+try {
+  await ensureLatestFromRegistry(PACKAGE_NAME);
+} catch (err) {
+  console.error(`>> ${PACKAGE_NAME}: update re-exec failed (${err.message}), using current`);
+}
+
+await startMcpServer();

package/src/lib/check-update.js

@@ -0,0 +1,92 @@
+/**
+ * 启动前检查 npm 最新版，若有更新则 npx 拉取并重 exec（stdio MCP 入口共用）
+ */
+import { readFileSync } from "fs";
+import { spawn } from "child_process";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const SKIP_ENV = "DOCS_MCP_SKIP_UPDATE";
+const REGISTRY_ENV = "DOCS_MCP_REGISTRY";
+const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+
+function readPackageVersion() {
+  const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+  const pkg = JSON.parse(readFileSync(path.join(pkgRoot, "package.json"), "utf-8"));
+  return { version: pkg.version, name: pkg.name, root: pkgRoot };
+}
+
+function isNewer(latest, current) {
+  const a = latest.split(".").map((n) => parseInt(n, 10) || 0);
+  const b = current.split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const x = a[i] ?? 0;
+    const y = b[i] ?? 0;
+    if (x > y) return true;
+    if (x < y) return false;
+  }
+  return false;
+}
+
+/** npm registry 路径：scoped 包需将 `/` 编码为 `%2F`（如 @urovotest/pkg → @urovotest%2Fpkg） */
+function registryPackagePath(packageName) {
+  return packageName.replace("/", "%2F");
+}
+
+async function fetchLatestVersion(packageName) {
+  const registry = (process.env[REGISTRY_ENV] || DEFAULT_REGISTRY).replace(/\/$/, "");
+  const url = `${registry}/${registryPackagePath(packageName)}/latest`;
+  const res = await fetch(url, { signal: AbortSignal.timeout(8000) });
+  if (res.status === 404) return null;
+  if (!res.ok) throw new Error(`registry HTTP ${res.status}`);
+  const data = await res.json();
+  return data.version;
+}
+
+function reexecViaNpx(packageName, version) {
+  return new Promise((resolve, reject) => {
+    const spec = `${packageName}@${version}`;
+    console.error(`>> ${packageName}: syncing to latest ${version} via npx...`);
+    const child = spawn("npx", ["-y", spec], {
+      stdio: "inherit",
+      shell: true,
+      env: { ...process.env, [SKIP_ENV]: "1" },
+    });
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      process.exit(code ?? 0);
+    });
+    resolve(true);
+  });
+}
+
+/**
+ * @returns {Promise<boolean>} true = 已 spawn 新版本进程，当前进程即将退出
+ */
+export async function ensureLatestFromRegistry(packageName) {
+  if (process.env[SKIP_ENV] === "1") return false;
+
+  const { version: current } = readPackageVersion();
+
+  let latest;
+  try {
+    latest = await fetchLatestVersion(packageName);
+  } catch (err) {
+    console.error(`>> ${packageName}: update check skipped (${err.message})`);
+    return false;
+  }
+
+  if (!latest) {
+    console.error(`>> ${packageName}: not on registry, using bundled v${current}`);
+    return false;
+  }
+
+  if (!isNewer(latest, current)) {
+    console.error(`>> ${packageName}: v${current} (latest)`);
+    return false;
+  }
+
+  console.error(`>> ${packageName}: v${current} -> v${latest}`);
+  await reexecViaNpx(packageName, latest);
+  return true;
+}

package/src/lib/create-mcp-server.js

@@ -0,0 +1,90 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { createDocsTools, callTool } from "./docs-tools.js";
+
+export function createUrovoSdkMcpServer(options = {}) {
+  const tools = createDocsTools(options);
+
+  const server = new Server(
+    { name: "urovosdk-docs", version: "1.0.0" },
+    { capabilities: { tools: {} } }
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+      {
+        name: "search_urovosdk_docs",
+        description: "Search UrovoSDK documentation (Pinpad, Printer, Scanner, EMV, read card, install). Use for integration questions.",
+        inputSchema: {
+          type: "object",
+          properties: { query: { type: "string" }, limit: { type: "number" } },
+          required: ["query"],
+        },
+      },
+      {
+        name: "list_urovosdk_docs",
+        description: "List all UrovoSDK documentation files.",
+        inputSchema: { type: "object", properties: {} },
+      },
+      {
+        name: "get_urovosdk_doc",
+        description: "Get full Markdown doc by path, e.g. 02-reference/general/pinpad.md",
+        inputSchema: {
+          type: "object",
+          properties: { path: { type: "string" } },
+          required: ["path"],
+        },
+      },
+      {
+        name: "lookup_urovosdk_api",
+        description: "Precise API lookup by module/method/classPath/keyword/demoActivity. Example: module=Pinpad method=getLastErrorCode",
+        inputSchema: {
+          type: "object",
+          properties: {
+            domain: { type: "string", description: "general | emv | undocumented" },
+            module: { type: "string", description: "e.g. Pinpad, Printer, Scanner, EMV API" },
+            method: { type: "string" },
+            classPath: { type: "string" },
+            keyword: { type: "string" },
+            demoActivity: { type: "string" },
+            limit: { type: "number" },
+          },
+        },
+      },
+      {
+        name: "lookup_urovosdk_emv",
+        description: "Lookup EMV kernel API, callbacks, enums. Same params as lookup_urovosdk_api; defaults domain=emv.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            module: { type: "string" },
+            method: { type: "string" },
+            keyword: { type: "string" },
+            limit: { type: "number" },
+          },
+        },
+      },
+      {
+        name: "lookup_urovosdk_error_code",
+        description: "Look up Pinpad or Printer error code (decimal or hex like 0xF0).",
+        inputSchema: {
+          type: "object",
+          properties: { code: { type: ["number", "string"] } },
+          required: ["code"],
+        },
+      },
+    ],
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+      const result = await callTool(tools, name, args ?? {});
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error: ${err.message}` }], isError: true };
+    }
+  });
+
+  return server;
+}

package/src/lib/docs-tools.js

@@ -0,0 +1,206 @@
+/**
+ * UrovoSDK Docs MCP — 共享工具逻辑
+ */
+import fs from "fs/promises";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_DOCS_PATH = path.resolve(__dirname, "../../docs");
+
+export function createDocsTools(options = {}) {
+  const remoteOnly = options.remoteOnly === true || process.env.MCP_REMOTE_ONLY === "1";
+  const DOCS_PATH = options.docsPath
+    ? path.resolve(options.docsPath)
+    : process.env.DOCS_PATH
+      ? path.resolve(process.env.DOCS_PATH)
+      : DEFAULT_DOCS_PATH;
+  const DOCS_URL = (options.docsUrl || process.env.DOCS_URL || "").replace(/\/$/, "");
+  const useRemote = remoteOnly || (!!DOCS_URL && (options.preferRemote || process.env.DOCS_PREFER_REMOTE === "1"));
+
+  async function readLocalFile(relativePath) {
+    return fs.readFile(path.join(DOCS_PATH, relativePath), "utf-8");
+  }
+
+  async function fetchRemote(relativePath) {
+    if (!DOCS_URL) throw new Error("DOCS_URL is not configured");
+    const url = `${DOCS_URL}/${relativePath.replace(/\\/g, "/")}`;
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`);
+    return res.text();
+  }
+
+  async function readDocFile(relativePath) {
+    if (useRemote || DOCS_URL) {
+      try {
+        return await fetchRemote(relativePath);
+      } catch (err) {
+        if (remoteOnly || useRemote) throw err;
+      }
+    }
+    return readLocalFile(relativePath);
+  }
+
+  const ERROR_CODES = {
+    0: { category: "pinpad", constant: "SUCCESS", message: "Success" },
+    1: { category: "pinpad", constant: "UNSUPPORTED_COMMAND", message: "Unsupported command" },
+    2: { category: "pinpad", constant: "COMMAND_LENGTH_ERROR", message: "Command length error" },
+    100: { category: "pinpad", constant: "PARAM_NULL", message: "Parameter is null or empty" },
+    101: { category: "pinpad", constant: "MISMATCH_DATA_LENGTH", message: "Mismatch data length" },
+    102: { category: "pinpad", constant: "INVALID_DATA_LENGTH", message: "Invalid data length" },
+    103: { category: "pinpad", constant: "INVALID_KEY_INDEX", message: "Invalid key index" },
+    104: { category: "pinpad", constant: "INVALID_PARAMETER", message: "Invalid parameter" },
+    105: { category: "pinpad", constant: "INVALID_RSA_PUBLIC_KEY", message: "Invalid RSA public key" },
+    106: { category: "pinpad", constant: "RUNTIME_EXCEPTION", message: "Runtime exception" },
+    0xF0: { category: "printer", constant: "NO_PAPER", message: "No paper" },
+    240: { category: "printer", constant: "NO_PAPER", message: "No paper" },
+    0xF3: { category: "printer", constant: "OVER_HEAT", message: "Over heat" },
+    243: { category: "printer", constant: "OVER_HEAT", message: "Over heat" },
+    0xE1: { category: "printer", constant: "LOW_VOLTAGE", message: "Low voltage" },
+    225: { category: "printer", constant: "LOW_VOLTAGE", message: "Low voltage" },
+    0xF2: { category: "printer", constant: "HARDWARE_ERROR", message: "Hardware error" },
+    242: { category: "printer", constant: "HARDWARE_ERROR", message: "Hardware error" },
+    0xF7: { category: "printer", constant: "PRINTER_BUSY", message: "Printer busy" },
+    247: { category: "printer", constant: "PRINTER_BUSY", message: "Printer busy" },
+  };
+
+  function tokenize(text) {
+    return text.toLowerCase().split(/[\s\-_/\\.:#]+/).filter(Boolean);
+  }
+
+  function scoreEntry(entry, queryTokens) {
+    const hay = `${entry.title} ${entry.path} ${entry.snippet || ""}`.toLowerCase();
+    let score = 0;
+    for (const t of queryTokens) {
+      if (hay.includes(t)) score += t.length > 3 ? 3 : 1;
+    }
+    return score;
+  }
+
+  async function loadIndex() {
+    try {
+      return JSON.parse(await readDocFile("search-index.json"));
+    } catch {
+      return { entries: [] };
+    }
+  }
+
+  async function loadRegistry() {
+    try {
+      return JSON.parse(await readDocFile("api-registry.json"));
+    } catch {
+      return { items: [] };
+    }
+  }
+
+  function scoreApiItem(item, tokens) {
+    const hay = [
+      item.domain, item.module, item.method, item.title, item.classPath,
+      item.demoActivity, item.purpose, item.signature, ...(item.keywords || []),
+    ].filter(Boolean).join(" ").toLowerCase();
+    let score = 0;
+    for (const t of tokens) {
+      if (hay.includes(t)) score += t.length >= 3 ? 3 : 1;
+    }
+    return score;
+  }
+
+  async function searchDocs(query, limit = 5) {
+    const index = await loadIndex();
+    const tokens = tokenize(query);
+    if (!tokens.length) return index.entries.slice(0, limit);
+    const ranked = index.entries
+      .map((e) => ({ ...e, score: scoreEntry(e, tokens) }))
+      .filter((e) => e.score > 0)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, limit);
+
+    const results = [];
+    for (const item of ranked) {
+      let excerpt = item.snippet || "";
+      try {
+        const full = await readDocFile(item.path);
+        const idx = full.toLowerCase().indexOf(tokens[0]);
+        excerpt = idx >= 0 ? full.slice(Math.max(0, idx - 80), idx + 400) : full.slice(0, 500);
+      } catch { /* keep snippet */ }
+      results.push({ path: item.path, title: item.title, score: item.score, excerpt });
+    }
+    return results;
+  }
+
+  async function listDocs() {
+    const index = await loadIndex();
+    return index.entries.map(({ path: p, title }) => ({ path: p, title }));
+  }
+
+  async function getDoc(relativePath) {
+    const normalized = relativePath.replace(/\\/g, "/").replace(/^\//, "");
+    if (normalized.includes("..")) throw new Error("Invalid path");
+    return readDocFile(normalized);
+  }
+
+  function lookupErrorCode(code) {
+    const num = typeof code === "string" && code.startsWith("0x")
+      ? parseInt(code, 16)
+      : Number(code);
+    const info = ERROR_CODES[num] ?? ERROR_CODES[code];
+    if (!info) return { found: false, code };
+    return { found: true, code: num, ...info, doc: "02-reference/error-codes.md" };
+  }
+
+  async function lookupApi({ domain, module, method, classPath, keyword, demoActivity, limit = 10 }) {
+    const registry = await loadRegistry();
+    const parts = [domain, module, method, classPath, keyword, demoActivity].filter(Boolean);
+    const tokens = parts.join(" ").toLowerCase().split(/[\s\-_/\\.:#]+/).filter(Boolean);
+    if (!tokens.length) {
+      return { error: "Provide at least one of: domain, module, method, classPath, keyword, demoActivity" };
+    }
+    const ranked = registry.items
+      .map((item) => ({ ...item, score: scoreApiItem(item, tokens) }))
+      .filter((item) => item.score > 0)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, limit);
+    return {
+      query: { domain, module, method, classPath, keyword, demoActivity },
+      matchCount: ranked.length,
+      results: ranked,
+    };
+  }
+
+  async function lookupEmv(args) {
+    return lookupApi({ ...args, domain: args.domain || "emv" });
+  }
+
+  return {
+    docsPath: DOCS_PATH,
+    docsUrl: DOCS_URL,
+    remoteOnly,
+    searchDocs,
+    listDocs,
+    getDoc,
+    lookupErrorCode,
+    lookupApi,
+    lookupEmv,
+    loadIndex,
+    loadRegistry,
+  };
+}
+
+export async function callTool(tools, name, args = {}) {
+  switch (name) {
+    case "search_urovosdk_docs":
+      return { query: args.query, results: await tools.searchDocs(args.query, args.limit ?? 5) };
+    case "list_urovosdk_docs":
+      return await tools.listDocs();
+    case "get_urovosdk_doc":
+      return { path: args.path, content: await tools.getDoc(args.path) };
+    case "lookup_urovosdk_error_code":
+      return tools.lookupErrorCode(args.code);
+    case "lookup_urovosdk_api":
+      return await tools.lookupApi(args);
+    case "lookup_urovosdk_emv":
+      return await tools.lookupEmv(args);
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}

package/src/server.js

@@ -0,0 +1,10 @@
+/**
+ * UrovoSDK Docs MCP — stdio 服务（方案 C：bundled docs）
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createUrovoSdkMcpServer } from "./lib/create-mcp-server.js";
+
+export async function startMcpServer() {
+  const server = createUrovoSdkMcpServer();
+  await server.connect(new StdioServerTransport());
+}