ArcSuite MCP Server

ArcSuite MCP Server is a generic, read-only semantic MCP gateway for a licensed FUJIFILM ArcSuite Web Service Interface. It lets MCP-compatible AI clients discover configured document scopes, search and page through results, inspect metadata, list folders and revisions, batch-read document metadata, read bounded text from document content, and check document integrity.

This is an independent open-source project. It is not affiliated with or endorsed by FUJIFILM Business Innovation. See NOTICE.md.

What it provides

• v1.0 R1 Core Read: document search, semantic attribute filters, metadata, paths, folder listing, and revision listing;

• v1.0 R2 Content Read: SOAP/MTOM retrieval through a Java adapter, safe text extraction, size/character bounds, and signed cursors;

• v1.1 Read UX & Efficiency: profile-aware capability discovery, stable bounded search/folder paging, batch metadata reads, short-lived extracted-content reuse, and optional trusted ArcSuite UI deep links;

• v1.2 S1 Typed Search Foundation: schema-validated typed semantic predicates, enum aliases, and scope-configured full-text modes;

• v1.2 S2 Content Labels: operator-configured semantic content-label aliases, metadata membership proof, label-isolated extraction caches, and label-bound read cursors;

• v1.2 S3 Hard References: opt-in, single-hop incoming relationship discovery, candidate authorization before paging, and semantic results without physical relationship IDs;

• v1.2 S4 Document Integrity: per-scope opt-in validation and optional already-calculated evidence availability, with conservative status mapping;

• Contract vNext P1/P2: opt-in authenticated opaque search/continuation/result refs plus seven authority-bound continue, exact-replay, metadata, revisions, and bounded-content operations. Refs are non-credentials; current bearer, tool, scope, provider identity, root, type, and semantic authority are rechecked on consumption;

• current MCP Streamable HTTP through the official TypeScript SDK, with a stateless legacy compatibility path for older 2025-era clients;

• server-side scope mapping, token profiles, rate limits, audit metadata, and mechanical read-only operation checks.

The legacy v1.0 through v1.2 surface has ten semantic tools; each profile sees only the tools it allows:

arcsuite_describe_capabilities, arcsuite_search_documents, arcsuite_get_document, arcsuite_get_documents, arcsuite_list_folder, arcsuite_list_document_revisions, arcsuite_get_document_content_info, arcsuite_read_document, arcsuite_list_hard_references, and arcsuite_validate_document_integrity.

When the operator explicitly enables opaque refs on a verified single-runtime gateway and a token profile allows them, P2 adds arcsuite_continue_search, arcsuite_replay_search, arcsuite_get_document_by_ref, arcsuite_get_documents_by_ref, arcsuite_list_document_revisions_by_ref, arcsuite_get_document_content_info_by_ref, and arcsuite_read_document_by_ref. Legacy tools and response defaults remain unchanged. Restart invalidates refs; multi-replica operation and Dify v4.3 integration are not provided in P2.

See docs/tools.md for integrity validation, typed predicates, full-text modes, relationship reads, paging, batch-read, cache, and deep-link behavior. S1–S4 implementation is present and covered by synthetic tests. The F1–F7 closure remediation and Closure Remediation Round 2 are implemented and covered by the local cross-boundary regression suite; an independent Astra High final cross-cutting re-audit and live ArcSuite qualification remain pending.

Related MCP server: DICOMweb MCP Server

Architecture

flowchart TD
    Client["MCP client"] --> MCP["MCP Streamable HTTP"]
    MCP --> Semantic["Semantic tool registry"]
    Semantic --> Scope["Scope and policy registry"]
    Semantic --> Paging["Bounded ID snapshot cache"]
    Semantic --> Bridge["Bounded content bridge"]
    Bridge --> Cache["Short-lived extracted-text cache"]
    Scope --> Adapter["Java ArcSuite adapter"]
    Paging --> Adapter
    Bridge --> Adapter
    Adapter --> ArcSuite["Licensed ArcSuite service"]

The project is not a generic ArcSuite SOAP proxy. MCP callers do not provide an ArcSuite endpoint, cabinet ID, physical Attribute ID, WSDL, SOAP operation, credential, or session identifier. Those values stay in operator configuration and the adapter.

Prerequisites

• Node.js 22.6 or newer;

• Python 3 for bounded OOXML extraction;

• pdftotext for PDF extraction;

• Java 17 JDK or newer for the optional SOAP/MTOM adapter;

• ArcSuite Web Service Interface documentation and a WSDL obtained from the operator's licensed environment for a real deployment.

Vendor material is not included. See docs/vendor-references.md.

Quick start with the synthetic adapter

The mock mode never contacts ArcSuite and uses only synthetic documents:

npm ci
MCP_DEV_BEARER_TOKEN=local-example-token npm run dev

The endpoint listens on http://127.0.0.1:8080/mcp. A minimal request is:

curl -sS http://127.0.0.1:8080/mcp \
  -H 'Authorization: Bearer local-example-token' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-03-26' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"arcsuite_search_documents","arguments":{"scope":"example_documents","filters":{"document_number":"DOC-000001"}}}}'

For an operator deployment, copy docker-compose.example.yml (or the Podman template) to ignored local paths, replace every placeholder with values verified in the licensed environment, and run the Java adapter in a private network. See docs/getting-started.md and docs/deployment.md.

Configuration

The semantic registry is the safe place to map public names to environment- specific ArcSuite schema. Start with config/scopes.example.yaml:

version: 1
scopes:
  example_documents:
    description: "Example document repository"
    enabled: true
    arcsuite:
      cabinet_alias: "EXAMPLE_CABINET"
      cabinet_id: "rep:YOUR_SERVICE:YOUR_CABINET"
      root_object_id: null
      resolve_references: true
    # Optional labels are semantic aliases for callers. The physical mapping
    # is operator configuration and is never returned through MCP.
    # content_labels:
    #   preview:
    #     ns: "rep"
    #     name: "user:YOUR_PREVIEW_CONTENT_LABEL"
    # Optional convenience; the host/template remain server-side. HTTPS is the
    # default and the complete semantic document ID is URL-encoded.
    # ui:
    #   document_url_template: "https://arcsuite.example.invalid/open?id={document_id}"
    # For a trusted internal HTTP-only UI, opt in for this scope and use the
    # native ArcSuite object ID placeholder:
    #   allow_http: true
    #   document_url_template: "http://arcsuite-internal.example.invalid/ArcSuite/docspace/sdk/open.do?id={arcsuite_object_id}&enc=UTF-8"
    allowed_object_types: [document, folder, reference]
    default_attr_ids:
      - {ns: "rep", name: "system:name"}
    search:
      full_text_modes: [none]
    semantic_attributes:
      document_number:
        attr_id: {ns: "rep", name: "user:YOUR_DOCUMENT_NUMBER_ATTRIBUTE"}
        type: string
        operators: [eq, like]

The endpoint and credentials are environment or secret-file configuration, never MCP tool arguments. Token profiles are hashes of bearer tokens; use npm run hash-token -- 'a-local-token' for local setup and keep the resulting token configuration out of version control.

v1.1 paging/content caches are process-local and bounded by configuration. They are optimizations, not authorities: every content-info request, initial read, and cursor continuation re-proves current cabinet/root/type, effective object, revision, and content-label membership before a cache or cursor result is used. Private content snapshots include client profile, scope, requested and effective object identity, revision, semantic and physical label identity, extractor variant, and content hash. Read cursors use a signed opaque effective-identity binding; older cursor formats fail cleanly. Caches never write extracted document text to the audit log.

v1.2 typed filter values are validated against the configured ArcSuite schema. Explicit predicates use only the small semantic operator matrix documented in docs/tools.md; enum aliases hide physical values. Public status and semantic attributes expose a configured alias only after an exact, unambiguous physical mapping; otherwise the physical enum name/label is omitted. none is the default full-text mode, while stemming and thesaurus require explicit scope configuration.

S2 content reads accept semantic aliases such as system:primary (the default) and an operator-configured preview; callers cannot submit a physical namespace/name pair. The selected object or revision must advertise the exact namespace and name in rep:system:contentlabellist before content is fetched.

See docs/configuration.md for all important bounds and config/tokens.example.json for a synthetic profile.

MCP client example

Client configuration varies by product. A generic illustrative shape is:

{
  "mcpServers": {
    "arcsuite": {
      "url": "https://mcp.example.invalid/mcp",
      "headers": {
        "Authorization": "Bearer ${ARCSUITE_MCP_TOKEN}"
      }
    }
  }
}

The MCP endpoint is the only endpoint an AI client should reach. A Dify example, including self-hosted networking and SSRF-proxy guidance, is isolated under docs/integrations/dify.md and examples/dify/README.md.

Supported content types

The content bridge currently supports text, CSV, JSON, XML, PDF, DOCX, XLSX, and PPTX extraction where the corresponding local runtime is available. XML DTD/external entities are rejected. OOXML archive paths, file counts, decompression, member sizes, and extracted characters are bounded. Shared OOXML extraction uses an encoding-aware parser-level declaration/entity rejection before expansion; late and UTF-16 declarations are not accepted. JSON, text, and OOXML materialization is bounded by the configured output budget or a reviewed input bound; PDF subprocess output is bounded near the same budget. Macros and embedded objects are not executed. DocuWorks/XDW is intentionally unsupported in v1.x and fails safely unless a future optional provider is explicitly configured. No normal MCP tool returns binary or base64 content.

Security philosophy and non-goals

Read-only is enforced at several layers: tool definitions, input validation, semantic scope checks, the SOAP operation allowlist, adapter dispatch, and tests. Administrator mode, privilege assertion, privileged-print retrieval, ACL mutation, hard delete, workflow termination, delegated workflow execution, arbitrary SOAP operations, and arbitrary endpoint/cabinet/schema input are not v1.x capabilities.

The v1.1 ID-only paging operations and multi-object metadata read are themselves read-only and remain behind the same semantic scope checks. Paging/content caches are performance features, not authorities.

Future governed mutations, if ever added, require explicit human approval and workflow-controlled execution. Business mutation retry remains zero.

Development and testing

npm ci
npm run typecheck
npm test
npm run check:invariants
npm run check:hygiene
python3 -m py_compile scripts/ooxml_extract.py
(cd adapter-java && ./compile.sh && ./selftest.sh)

The repository's GitHub workflows run the same checks plus dependency and CodeQL jobs. Tests use synthetic fixtures. A passing local test suite is not a claim of qualification against a real ArcSuite server or a particular AI client; see docs/compatibility.md.

License

MIT. See LICENSE.