simple-dynamsoft-mcp: Instructions file for Codex

AGENTS.md

Purpose

This file is the operational guide for coding agents working in simple-dynamsoft-mcp. Use it as the default source for build/test workflows and coding conventions.

Project Snapshot

• Runtime: Node.js ESM ("type": "module"), Node >= 18 required.
• Main entrypoint: src/index.js.
• Server factory: src/server/create-server.js.
• Test framework: built-in node:test + node:assert/strict.
• Key domains: MCP tool registration, resource indexing, RAG providers, data bootstrap/submodule sync.
• Public MCP surface: dwt, ddv, dbr, mrz, mds, bbs; dcv may still appear in internal resource or version wiring, but do not expose it as a selectable product in tool parameters. Product-selection guidance (doc://product-selection, CAPABILITY_FACTS) may recommend DCV components (Camera Enhancer, Label Recognizer, Document Normalizer, Code Parser) when no packaged product covers a use case.
• bbs (Batch Barcode Scanner) is an Android/iOS app, not an SDK: docs only (data/documentation/batch-barcode-scanner-docs, edition mobile, platforms android/ios, registry key bbs-mobile), no samples. Each app's version comes from its own app/release-notes/<platform>.md (highest ## x.y.z heading; release-notes-headings strategy in scripts/sdk-version-sources.mjs) and is stored at bbs-mobile.platforms.<platform>.version; bbs-mobile.version is their max (the docs-set label that drives latestMajor and the URIs of generic pages). The platform release-notes pages carry their own platform version in the URI, and get_index lists platformVersions. get_quickstart, list_samples, and get_sample_files return reference links (buildBbsAppReferenceResponse) instead of code.
• Shared Capture Vision docs: DCV pages that DBR docs or DBR sidebars (_includes/) link to are indexed under dbr (tags shared, capture-vision; real capture-vision/docs URL; sourceVersion = DCV version). Selection lives in src/server/resource-index/shared-docs.js; a DCV source whose minor/build does not match the DBR edition is skipped with a shared_docs_version_mismatch warning.
• Doc URIs are doc://{product}/{edition}/{platform}/{version}/{path}, where path is the source file path without .md, without the programming/<lang>/ prefix, and with trailing /index dropped (full source path on collision). Shared DCV pages use dcv/... or dcv-core/... paths.
• Gemini index builds are incremental: every cached chunk carries a hash of model + text, and a build reuses vectors from any cache, checkpoint, or seeded previous release in RAG_CACHE_DIR, embedding only new or changed chunks (RAG_REBUILD=true forces a full re-embed). scripts/seed-rag-cache.sh seeds from the latest release; release and CI use it. Index builds happen only in the release workflow. In CI, test_gemini_provider runs only on pull requests that do not change indexed content (data/, resource-index code, src/rag/search-utils.js, src/rag/config.js); it seeds the latest release index (failing if none is seeded) and embeds only test queries, with RAG_MAX_EMBED_CHUNKS=50 as a backstop. PRs that change indexed content skip Gemini verification.