docuware-mcp 0.1.0__tar.gz

docuware_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: docuware-mcp
+Version: 0.1.0
+Summary: MCP server exposing a DocuWare DMS to LLM-based agents
+Author: Stefan Schönberger
+Author-email: Stefan Schönberger <stefan@sniner.dev>
+License-Expression: BSD-3-Clause
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: docuware-client>=0.7.10
+Requires-Dist: fastmcp>=2.0.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# docuware-mcp
+
+A Model Context Protocol (MCP) server that exposes a DocuWare DMS to
+LLM-based agents through a database-style API.
+
+This is an independent project with no affiliation to DocuWare GmbH.
+
+## Configuration
+
+Credentials are read from the `docuware-client` standard environment
+variables:
+
+```
+DW_URL=https://dms.example.com
+DW_USERNAME=service_account
+DW_PASSWORD=<secret>
+DW_ORG=<org>
+```
+
+Alternatively, point `DW_CREDENTIALS_FILE` at a JSON file — useful for
+switching between test and production systems, or for keeping secrets
+out of shell history:
+
+```
+DW_CREDENTIALS_FILE=/path/to/credentials.json
+```
+
+The file uses the same keys as the environment variables:
+
+```json
+{
+    "url": "https://dms.example.com",
+    "username": "service_account",
+    "password": "<secret>",
+    "organization": "Acme GmbH"
+}
+```
+
+`organization` is optional if the service account belongs to a single
+organization. Make sure the file is not world-readable (`chmod 600`).
+
+For internal DocuWare installations with self-signed or private-CA
+certificates, TLS verification can be disabled with
+`DW_VERIFY_CERT=false`. **Do not use this against production systems** —
+it disables protection against man-in-the-middle attacks.
+
+OAuth2 requires DocuWare 7.10 or later.
+
+## Use with an MCP client
+
+`docuware-mcp` is a stdio-based MCP server: an MCP client (Claude
+Desktop, Claude Code, …) launches it as a subprocess and talks to it
+over stdin/stdout. You don't run it yourself — the client does.
+
+The recommended install path is via [`uv`](https://docs.astral.sh/uv/),
+because `uvx` will fetch and run the package on demand without a global
+install. Install `uv` once (`brew install uv` on macOS,
+`curl -LsSf https://astral.sh/uv/install.sh | sh` on Linux,
+`irm https://astral.sh/uv/install.ps1 | iex` in PowerShell on Windows),
+then add this entry to your client's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "docuware": {
+      "command": "uvx",
+      "args": ["docuware-mcp"],
+      "env": {
+        "DW_CREDENTIALS_FILE": "/path/to/credentials.json"
+      }
+    }
+  }
+}
+```
+
+The config file lives at:
+
+- **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
+- **Claude Code**: `.mcp.json` in your project root (or run `claude mcp add docuware -- uvx docuware-mcp`)
+
+Restart the client after editing. The `docuware` server should then
+appear in the available-tools list, exposing `list_archives`,
+`describe_archive`, `search`, `get_document`, and `status`.
+
+### Running directly (for debugging)
+
+If you've cloned this repo and want to poke at the server with the
+[MCP Inspector](https://github.com/modelcontextprotocol/inspector)
+or call it from a script:
+
+```
+docuware-mcp
+```
+
+Speaks MCP over stdio — same protocol the clients above use.
+
+## License
+
+BSD-3-Clause.

docuware_mcp-0.1.0/README.md

@@ -0,0 +1,99 @@
+# docuware-mcp
+
+A Model Context Protocol (MCP) server that exposes a DocuWare DMS to
+LLM-based agents through a database-style API.
+
+This is an independent project with no affiliation to DocuWare GmbH.
+
+## Configuration
+
+Credentials are read from the `docuware-client` standard environment
+variables:
+
+```
+DW_URL=https://dms.example.com
+DW_USERNAME=service_account
+DW_PASSWORD=<secret>
+DW_ORG=<org>
+```
+
+Alternatively, point `DW_CREDENTIALS_FILE` at a JSON file — useful for
+switching between test and production systems, or for keeping secrets
+out of shell history:
+
+```
+DW_CREDENTIALS_FILE=/path/to/credentials.json
+```
+
+The file uses the same keys as the environment variables:
+
+```json
+{
+    "url": "https://dms.example.com",
+    "username": "service_account",
+    "password": "<secret>",
+    "organization": "Acme GmbH"
+}
+```
+
+`organization` is optional if the service account belongs to a single
+organization. Make sure the file is not world-readable (`chmod 600`).
+
+For internal DocuWare installations with self-signed or private-CA
+certificates, TLS verification can be disabled with
+`DW_VERIFY_CERT=false`. **Do not use this against production systems** —
+it disables protection against man-in-the-middle attacks.
+
+OAuth2 requires DocuWare 7.10 or later.
+
+## Use with an MCP client
+
+`docuware-mcp` is a stdio-based MCP server: an MCP client (Claude
+Desktop, Claude Code, …) launches it as a subprocess and talks to it
+over stdin/stdout. You don't run it yourself — the client does.
+
+The recommended install path is via [`uv`](https://docs.astral.sh/uv/),
+because `uvx` will fetch and run the package on demand without a global
+install. Install `uv` once (`brew install uv` on macOS,
+`curl -LsSf https://astral.sh/uv/install.sh | sh` on Linux,
+`irm https://astral.sh/uv/install.ps1 | iex` in PowerShell on Windows),
+then add this entry to your client's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "docuware": {
+      "command": "uvx",
+      "args": ["docuware-mcp"],
+      "env": {
+        "DW_CREDENTIALS_FILE": "/path/to/credentials.json"
+      }
+    }
+  }
+}
+```
+
+The config file lives at:
+
+- **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
+- **Claude Code**: `.mcp.json` in your project root (or run `claude mcp add docuware -- uvx docuware-mcp`)
+
+Restart the client after editing. The `docuware` server should then
+appear in the available-tools list, exposing `list_archives`,
+`describe_archive`, `search`, `get_document`, and `status`.
+
+### Running directly (for debugging)
+
+If you've cloned this repo and want to poke at the server with the
+[MCP Inspector](https://github.com/modelcontextprotocol/inspector)
+or call it from a script:
+
+```
+docuware-mcp
+```
+
+Speaks MCP over stdio — same protocol the clients above use.
+
+## License
+
+BSD-3-Clause.

docuware_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "docuware-mcp"
+version = "0.1.0"
+description = "MCP server exposing a DocuWare DMS to LLM-based agents"
+authors = [{ name = "Stefan Schönberger", email = "stefan@sniner.dev" }]
+requires-python = ">=3.10"
+readme = "README.md"
+license = "BSD-3-Clause"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "docuware-client>=0.7.10",
+    "fastmcp>=2.0.0",
+]
+
+[project.scripts]
+docuware-mcp = "docuware_mcp.server:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.2.2,<9",
+    "basedpyright>=1.38.2,<2",
+    "ruff>=0.15.5,<0.16",
+]
+
+[tool.uv]
+default-groups = "all"
+
+[build-system]
+requires = ["uv-build>=0.10.9,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "docuware_mcp"
+
+[tool.pytest.ini_options]
+addopts = "-ra -q"
+testpaths = ["tests"]
+
+[tool.pyright]
+typeCheckingMode = "standard"
+useLibraryCodeForTypes = true
+venvPath = "."
+venv = ".venv"
+
+[tool.ruff]
+line-length = 96
+
+[tool.ruff.lint]
+ignore = ["E402"]
+per-file-ignores = { "__init__.py" = ["F401"] }

docuware_mcp-0.1.0/src/docuware_mcp/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

docuware_mcp-0.1.0/src/docuware_mcp/filters.py

@@ -0,0 +1,271 @@
+"""Filter DSL → docuware-client conditions translation.
+
+Operators (v1):
+
+- bare value (or ``{"eq": v}``): exact match
+- ``{"like": "*pattern*"}``: wildcard match (``*`` and ``?``)
+- ``{"gte": v}`` / ``{"lte": v}``: ≥ / ≤ inclusive
+- ``{"between": [low, high]}``: low ≤ field ≤ high (use ``null`` for open bound)
+- ``{"empty": true}`` (or value ``null``): field is empty
+
+Combinator (top-level): ``"AND"`` (default) or ``"OR"``. Flat — no nested groups.
+
+Limitations (per design — see docuware-mcp-design-decisions.md):
+
+- No ``gt`` / ``lt`` (DW only has inclusive ranges)
+- No ``ne``, ``in``, ``regex`` (would require backend-fakery)
+- No nested boolean groups (DW backend has one global combinator)
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from typing import Any, Dict, List
+
+import docuware
+
+from docuware_mcp.schema import ArchiveSchema, FieldSchema
+
+
+class FilterValidationError(ValueError):
+    """Raised when the filter DSL contains an invalid construct."""
+
+
+_DW_METACHARS = "()*?"
+
+
+def _escape_dw(value: str, *, escape_wildcards: bool) -> str:
+    """Escape DocuWare metacharacters in a string value.
+
+    ``*`` and ``?`` are escaped only when ``escape_wildcards`` is True. Already
+    backslash-escaped sequences are left alone, so the function is idempotent.
+    """
+    chars = _DW_METACHARS if escape_wildcards else "()"
+    out: List[str] = []
+    i = 0
+    n = len(value)
+    while i < n:
+        c = value[i]
+        if c == "\\" and i + 1 < n and value[i + 1] in _DW_METACHARS:
+            out.append(c)
+            out.append(value[i + 1])
+            i += 2
+            continue
+        if c in chars:
+            out.append("\\")
+        out.append(c)
+        i += 1
+    return "".join(out)
+
+
+def _coerce(value: Any, fld: FieldSchema) -> Any:
+    """Coerce a JSON value to the type matching the field's DW type.
+
+    Strings remain strings on text-like fields; ISO strings become ``date``,
+    ``datetime``, ``int``, or ``float`` on the typed fields. Failures raise
+    :class:`FilterValidationError` with an LLM-actionable message.
+    """
+    if value is None:
+        return None
+
+    ftype = (fld.type or "").lower()
+
+    if ftype == "date":
+        if isinstance(value, datetime):
+            return value.date()
+        if isinstance(value, date):
+            return value
+        if isinstance(value, str):
+            try:
+                return date.fromisoformat(value)
+            except ValueError as exc:
+                raise FilterValidationError(
+                    f"Field {fld.name!r} is type Date — value {value!r} is not a "
+                    f"valid ISO date (YYYY-MM-DD)"
+                ) from exc
+        raise FilterValidationError(
+            f"Field {fld.name!r} is type Date — expected ISO date string, got "
+            f"{type(value).__name__}"
+        )
+
+    if ftype == "datetime":
+        if isinstance(value, datetime):
+            return value
+        if isinstance(value, date):
+            return datetime(value.year, value.month, value.day)
+        if isinstance(value, str):
+            try:
+                return datetime.fromisoformat(value)
+            except ValueError as exc:
+                raise FilterValidationError(
+                    f"Field {fld.name!r} is type DateTime — value {value!r} is not "
+                    f"valid ISO 8601"
+                ) from exc
+        raise FilterValidationError(
+            f"Field {fld.name!r} is type DateTime — expected ISO datetime string, got "
+            f"{type(value).__name__}"
+        )
+
+    if ftype in ("numeric", "int"):
+        if isinstance(value, bool):
+            raise FilterValidationError(
+                f"Field {fld.name!r} is type Numeric — got bool"
+            )
+        if isinstance(value, int):
+            return value
+        if isinstance(value, str):
+            try:
+                return int(value)
+            except ValueError as exc:
+                raise FilterValidationError(
+                    f"Field {fld.name!r} is type Numeric — value {value!r} is not an integer"
+                ) from exc
+        raise FilterValidationError(
+            f"Field {fld.name!r} is type Numeric — expected integer, got "
+            f"{type(value).__name__}"
+        )
+
+    if ftype == "decimal":
+        if isinstance(value, bool):
+            raise FilterValidationError(
+                f"Field {fld.name!r} is type Decimal — got bool"
+            )
+        if isinstance(value, (int, float)):
+            return float(value)
+        if isinstance(value, str):
+            try:
+                return float(value)
+            except ValueError as exc:
+                raise FilterValidationError(
+                    f"Field {fld.name!r} is type Decimal — value {value!r} is not a number"
+                ) from exc
+        raise FilterValidationError(
+            f"Field {fld.name!r} is type Decimal — expected number, got "
+            f"{type(value).__name__}"
+        )
+
+    # Text, Memo, Keyword, unknown: pass strings through, stringify others.
+    return value if isinstance(value, str) else str(value)
+
+
+def _format(value: Any, *, escape_wildcards: bool) -> Any:
+    """Apply DW metacharacter escaping; pass non-strings through unchanged.
+
+    The returned value is suitable for the dict form of
+    :meth:`docuware.SearchDialog.search` when called with
+    ``quote=QuoteMode.NONE`` (i.e. the client does no further escaping).
+    """
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return _escape_dw(value, escape_wildcards=escape_wildcards)
+    return value
+
+
+def _translate_one(fld: FieldSchema, spec: Any) -> Any:
+    """Translate one ``(field, spec)`` pair to the value form expected by DW."""
+    allowed = set(fld.operators)
+
+    # Shorthand: null value means "field is empty"
+    if spec is None:
+        if "empty" not in allowed:
+            raise FilterValidationError(
+                f"Field {fld.name!r} (type={fld.type}) does not support 'empty' check"
+            )
+        return None
+
+    # Operator dict
+    if isinstance(spec, dict):
+        if len(spec) != 1:
+            raise FilterValidationError(
+                f"Field {fld.name!r}: filter must be a single-operator dict, got "
+                f"keys {list(spec.keys())}"
+            )
+        op, raw = next(iter(spec.items()))
+        if op not in allowed:
+            raise FilterValidationError(
+                f"Field {fld.name!r} (type={fld.type}) does not support operator {op!r}. "
+                f"Allowed: {', '.join(sorted(allowed))}"
+            )
+
+        if op == "empty":
+            return None
+
+        if op == "eq":
+            return _format(_coerce(raw, fld), escape_wildcards=True)
+
+        if op == "like":
+            if not isinstance(raw, str):
+                raise FilterValidationError(
+                    f"Field {fld.name!r}: 'like' requires a string value, got "
+                    f"{type(raw).__name__}"
+                )
+            return _format(raw, escape_wildcards=False)
+
+        if op == "gte":
+            return [_format(_coerce(raw, fld), escape_wildcards=True), None]
+
+        if op == "lte":
+            return [None, _format(_coerce(raw, fld), escape_wildcards=True)]
+
+        if op == "between":
+            if not isinstance(raw, (list, tuple)) or len(raw) != 2:
+                raise FilterValidationError(
+                    f"Field {fld.name!r}: 'between' requires a 2-element list "
+                    f"[low, high] (use null for an open bound)"
+                )
+            low, high = raw
+            return [
+                _format(_coerce(low, fld), escape_wildcards=True) if low is not None else None,
+                _format(_coerce(high, fld), escape_wildcards=True) if high is not None else None,
+            ]
+
+        # Unreachable: 'allowed' check above filtered unsupported operators.
+        raise FilterValidationError(
+            f"Internal: operator {op!r} accepted but not implemented"
+        )
+
+    # Bare value = eq
+    if "eq" not in allowed:
+        raise FilterValidationError(
+            f"Field {fld.name!r} (type={fld.type}) does not support 'eq'"
+        )
+    return _format(_coerce(spec, fld), escape_wildcards=True)
+
+
+def build_conditions(filters: Dict[str, Any], schema: ArchiveSchema) -> Dict[str, Any]:
+    """Translate the filter DSL to a dict for ``SearchDialog.search()``.
+
+    The returned dict must be passed to docuware-client with
+    ``quote=docuware.QuoteMode.NONE`` because all values have already been
+    escaped according to their per-operator wildcard intent.
+    """
+    if not isinstance(filters, dict):
+        raise FilterValidationError(
+            f"filters must be an object, got {type(filters).__name__}"
+        )
+
+    out: Dict[str, Any] = {}
+    for fname, spec in filters.items():
+        try:
+            fld = schema.field_by_name(fname)
+        except KeyError:
+            raise FilterValidationError(
+                f"Unknown field {fname!r}. Available: {', '.join(schema.field_names())}"
+            ) from None
+        if fld.internal_id in out:
+            raise FilterValidationError(
+                f"Field {fname!r} resolves to {fld.internal_id!r} which already has "
+                f"a condition (multiple conditions on the same field are not supported)"
+            )
+        out[fld.internal_id] = _translate_one(fld, spec)
+    return out
+
+
+def parse_combinator(value: str) -> docuware.Operation:
+    upper = (value or "AND").upper()
+    if upper == "AND":
+        return docuware.Operation.AND
+    if upper == "OR":
+        return docuware.Operation.OR
+    raise FilterValidationError(f"combinator must be 'AND' or 'OR', got {value!r}")

docuware_mcp-0.1.0/src/docuware_mcp/schema.py

@@ -0,0 +1,106 @@
+"""Archive schema and field-type → operator mapping.
+
+The mapping is a static table held in the MCP server. We deliberately do
+not derive it from DocuWare's own ``OperatorTable``: the MCP-facing
+operator vocabulary is intentionally smaller than what DW would accept,
+so the LLM's mental model stays simple and consistent.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import asdict, dataclass, field
+from typing import Any, Dict, FrozenSet, List, Optional
+
+import docuware
+
+log = logging.getLogger(__name__)
+
+
+# DocuWare DWFieldType values observed in the wild are case-insensitive.
+# Keys here are lowercased before lookup.
+_TYPE_OPERATORS: Dict[str, FrozenSet[str]] = {
+    "text":     frozenset({"eq", "like", "empty"}),
+    "memo":     frozenset({"eq", "like", "empty"}),
+    "keyword":  frozenset({"eq", "like", "empty"}),
+    "keywords": frozenset({"eq", "like", "empty"}),
+    "numeric":  frozenset({"eq", "gte", "lte", "between", "empty"}),
+    "int":      frozenset({"eq", "gte", "lte", "between", "empty"}),
+    "decimal":  frozenset({"eq", "gte", "lte", "between", "empty"}),
+    "date":     frozenset({"eq", "gte", "lte", "between", "empty"}),
+    "datetime": frozenset({"eq", "gte", "lte", "between", "empty"}),
+}
+
+_DEFAULT_OPERATORS: FrozenSet[str] = frozenset({"eq", "empty"})
+
+
+def allowed_operators_for_type(dw_type: Optional[str]) -> FrozenSet[str]:
+    """Return the operator set the MCP DSL allows on a field of this DW type."""
+    if not dw_type:
+        return _DEFAULT_OPERATORS
+    return _TYPE_OPERATORS.get(dw_type.lower(), _DEFAULT_OPERATORS)
+
+
+@dataclass(frozen=True)
+class FieldSchema:
+    name: str
+    internal_id: str
+    type: Optional[str]
+    length: int
+    operators: List[str]
+    select_list: Optional[List[str]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class ArchiveSchema:
+    name: str
+    internal_id: str
+    fields: List[FieldSchema] = field(default_factory=list)
+
+    def field_by_name(self, name: str) -> FieldSchema:
+        cf = name.casefold()
+        for f in self.fields:
+            if f.name.casefold() == cf or f.internal_id.casefold() == cf:
+                return f
+        raise KeyError(name)
+
+    def field_names(self) -> List[str]:
+        return [f.name for f in self.fields]
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "name": self.name,
+            "internal_id": self.internal_id,
+            "fields": [f.to_dict() for f in self.fields],
+        }
+
+
+def describe_dialog(
+    dialog: docuware.SearchDialog, archive_name: str, archive_id: str
+) -> ArchiveSchema:
+    """Build an ArchiveSchema from a SearchDialog's field definitions."""
+    out: List[FieldSchema] = []
+    for sf in dialog.fields.values():
+        ops = sorted(allowed_operators_for_type(sf.type))
+        select_list: Optional[List[str]] = None
+        if sf.type and sf.type.lower() in ("keyword", "keywords"):
+            try:
+                values = sf.values()
+                if values:
+                    select_list = [str(v) for v in values]
+            except Exception as exc:
+                log.debug("select_list fetch failed for field %r: %s", sf.id, exc)
+        out.append(
+            FieldSchema(
+                name=sf.name,
+                internal_id=sf.id,
+                type=sf.type,
+                length=sf.length if sf.length is not None else -1,
+                operators=ops,
+                select_list=select_list,
+            )
+        )
+    return ArchiveSchema(name=archive_name, internal_id=archive_id, fields=out)

docuware_mcp-0.1.0/src/docuware_mcp/server.py

@@ -0,0 +1,326 @@
+"""docuware-mcp — MCP server exposing a DocuWare DMS to LLM-based agents."""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from typing import Any, Dict, Iterable, List, Optional, Set, Tuple
+
+import docuware
+from fastmcp import FastMCP
+
+from docuware_mcp.filters import (
+    FilterValidationError,
+    build_conditions,
+    parse_combinator,
+)
+from docuware_mcp.schema import ArchiveSchema, describe_dialog
+
+log = logging.getLogger("docuware_mcp")
+
+
+_SCHEMA_TTL_SECONDS = 300.0
+
+_client: Optional[docuware.Client] = None
+_schema_cache: Dict[str, Tuple[float, ArchiveSchema]] = {}
+
+
+def _verify_cert_from_env() -> bool:
+    raw = os.environ.get("DW_VERIFY_CERT")
+    if raw is None:
+        return True
+    return raw.strip().lower() not in ("0", "false", "no", "off")
+
+
+def _get_client() -> docuware.Client:
+    global _client
+    if _client is None:
+        verify = _verify_cert_from_env()
+        if not verify:
+            log.warning("DW_VERIFY_CERT disabled — TLS certificate not verified")
+        creds_file = os.environ.get("DW_CREDENTIALS_FILE")
+        if creds_file:
+            log.info("Connecting to DocuWare with credentials from %s", creds_file)
+            _client = docuware.connect(
+                credentials_file=creds_file, verify_certificate=verify
+            )
+        else:
+            log.info("Connecting to DocuWare via docuware.connect()")
+            _client = docuware.connect(verify_certificate=verify)
+    return _client
+
+
+def _resolve_archive(client: docuware.Client, name_or_id: str) -> docuware.FileCabinet:
+    """Resolve an archive across all organizations by ID or display name.
+
+    Baskets are excluded — this server exposes archives only.
+    """
+    candidates: List[docuware.FileCabinet] = []
+    cf = name_or_id.casefold()
+    for org in client.organizations:
+        for fc in org.file_cabinets:
+            if not isinstance(fc, docuware.FileCabinet) or fc.is_basket:
+                continue
+            if fc.id == name_or_id:
+                return fc
+            if fc.name.casefold() == cf:
+                candidates.append(fc)
+    if not candidates:
+        raise ValueError(f"Archive not found: {name_or_id!r}")
+    if len(candidates) > 1:
+        names = [
+            f"{c.name} [id={c.id}, org={c.organization.name}]" for c in candidates
+        ]
+        raise ValueError(
+            f"Archive name {name_or_id!r} is ambiguous across organizations. "
+            f"Use the internal ID instead. Candidates: {names}"
+        )
+    return candidates[0]
+
+
+def _get_search_dialog(fc: docuware.FileCabinet) -> docuware.SearchDialog:
+    dlg = fc.search_dialog(required=True)
+    if not isinstance(dlg, docuware.SearchDialog):
+        raise RuntimeError(
+            f"Archive {fc.name!r} returned unexpected dialog type {type(dlg).__name__}"
+        )
+    return dlg
+
+
+def _get_schema(client: docuware.Client, archive: str) -> ArchiveSchema:
+    now = time.monotonic()
+    cached = _schema_cache.get(archive)
+    if cached and (now - cached[0]) < _SCHEMA_TTL_SECONDS:
+        return cached[1]
+    fc = _resolve_archive(client, archive)
+    dlg = _get_search_dialog(fc)
+    schema = describe_dialog(dlg, fc.name, fc.id)
+    _schema_cache[archive] = (now, schema)
+    _schema_cache[fc.id] = (now, schema)
+    log.info("Loaded schema for archive %r [id=%s]: %d fields",
+             fc.name, fc.id, len(schema.fields))
+    return schema
+
+
+def _fields_to_dict(
+    field_values: Any, allowed_ids: Optional[Set[str]] = None
+) -> Dict[str, Any]:
+    """Render a list of FieldValue objects to a ``{name: value}`` dict.
+
+    If ``allowed_ids`` is given, only fields whose internal ID is in the set
+    are emitted. This is used to suppress DocuWare system metadata that isn't
+    part of the archive's search-dialog schema (and thus not described to
+    callers via :func:`describe_archive`).
+    """
+    out: Dict[str, Any] = {}
+    for fv in field_values or []:
+        fid = getattr(fv, "id", None)
+        if allowed_ids is not None and fid not in allowed_ids:
+            continue
+        name = getattr(fv, "name", None) or fid
+        if not name:
+            continue
+        value = getattr(fv, "value", None)
+        if value is not None and hasattr(value, "isoformat"):
+            value = value.isoformat()
+        out[name] = value
+    return out
+
+
+def _extract_doc_id(field_values: Iterable[Any]) -> Optional[str]:
+    """Pull the DWDOCID value out of a FieldValue list as a string."""
+    for fv in field_values or []:
+        if getattr(fv, "id", None) == "DWDOCID":
+            value = getattr(fv, "value", None)
+            return str(value) if value is not None else None
+    return None
+
+
+# --- MCP server ---
+
+mcp = FastMCP("docuware-mcp")
+
+
+@mcp.tool()
+def list_archives() -> List[Dict[str, str]]:
+    """List archives accessible to the configured DocuWare service account.
+
+    Analogous to ``SHOW DATABASES``. Returns each archive's display name,
+    internal ID, and the organization it belongs to. Baskets are excluded.
+    """
+    client = _get_client()
+    out: List[Dict[str, str]] = []
+    for org in client.organizations:
+        for fc in org.file_cabinets:
+            if fc.is_basket:
+                continue
+            out.append({
+                "name": fc.name,
+                "id": fc.id,
+                "organization": org.name,
+            })
+    log.info("list_archives → %d archives", len(out))
+    return out
+
+
+@mcp.tool()
+def describe_archive(archive: str) -> Dict[str, Any]:
+    """Describe an archive's schema: fields, types, and allowed operators.
+
+    Analogous to ``DESCRIBE TABLE``. The ``operators`` list per field tells you
+    which operators are valid in :func:`search`'s ``filters`` for that field.
+    Keyword fields with a defined value list also expose ``select_list``.
+
+    Args:
+        archive: Display name or internal ID of the archive.
+    """
+    client = _get_client()
+    schema = _get_schema(client, archive)
+    return schema.to_dict()
+
+
+@mcp.tool()
+def search(
+    archive: str,
+    filters: Optional[Dict[str, Any]] = None,
+    combinator: str = "AND",
+    limit: int = 25,
+    offset: int = 0,
+) -> Dict[str, Any]:
+    """Search documents in an archive using the structured filter DSL.
+
+    Args:
+        archive: Display name or internal ID of the archive.
+        filters: Dict mapping field names to either a bare value (= ``eq``) or
+            a single-operator dict like ``{"gte": 100}``. Supported operators:
+            ``eq``, ``like``, ``gte``, ``lte``, ``between``, ``empty``. Use
+            :func:`describe_archive` to see which operators each field accepts.
+        combinator: How multiple conditions are combined: ``"AND"`` (default)
+            or ``"OR"``. DocuWare does not support mixed AND/OR in one query.
+        limit: Maximum results to return (1–200, default 25).
+        offset: Number of results to skip (client-side slicing).
+
+    Returns:
+        A dict with ``items`` (list of result dicts containing ``id``,
+        ``title``, ``content_type``, ``fields``), ``count`` (server-reported
+        total when known), ``limit``, and ``offset``.
+    """
+    if not 1 <= limit <= 200:
+        raise ValueError("limit must be between 1 and 200")
+    if offset < 0:
+        raise ValueError("offset must be >= 0")
+
+    client = _get_client()
+    schema = _get_schema(client, archive)
+    fc = _resolve_archive(client, archive)
+
+    if not filters:
+        raise ValueError(
+            "search currently requires at least one filter condition. "
+            "Match-everything is not yet implemented in v1."
+        )
+
+    try:
+        conditions = build_conditions(filters, schema)
+    except FilterValidationError as exc:
+        raise ValueError(str(exc)) from None
+
+    op = parse_combinator(combinator)
+    dlg = _get_search_dialog(fc)
+
+    log.info(
+        "search archive=%r [id=%s] filters=%s combinator=%s limit=%d offset=%d",
+        fc.name, fc.id, list(filters.keys()), combinator, limit, offset,
+    )
+
+    result_iter = dlg.search(conditions, operation=op, quote=docuware.QuoteMode.NONE)
+    allowed_ids = {f.internal_id for f in schema.fields}
+
+    items: List[Dict[str, Any]] = []
+    skipped = 0
+    for item in result_iter:
+        if skipped < offset:
+            skipped += 1
+            continue
+        if len(items) >= limit:
+            break
+        items.append({
+            "id": _extract_doc_id(item.fields),
+            "title": item.title,
+            "content_type": item.content_type,
+            "fields": _fields_to_dict(item.fields, allowed_ids=allowed_ids),
+        })
+
+    return {
+        "items": items,
+        "count": getattr(result_iter, "count", None),
+        "limit": limit,
+        "offset": offset,
+    }
+
+
+@mcp.tool()
+def get_document(archive: str, document_id: str) -> Dict[str, Any]:
+    """Fetch a single document's metadata by primary-key ID.
+
+    Returns index field values, title, and content type. Does not return file
+    content — binary download will be a separate tool.
+
+    Args:
+        archive: Display name or internal ID of the archive.
+        document_id: DocuWare document ID (DWDOCID).
+    """
+    client = _get_client()
+    schema = _get_schema(client, archive)
+    fc = _resolve_archive(client, archive)
+    doc = fc.get_document(document_id)
+    allowed_ids = {f.internal_id for f in schema.fields}
+    return {
+        "id": str(getattr(doc, "id", document_id)),
+        "title": getattr(doc, "title", None),
+        "content_type": getattr(doc, "content_type", None),
+        "fields": _fields_to_dict(getattr(doc, "fields", None), allowed_ids=allowed_ids),
+    }
+
+
+@mcp.tool()
+def status() -> Dict[str, Any]:
+    """Connection health: organizations and visible archive count.
+
+    Useful as a first call to verify credentials and surface what the
+    configured service account can actually see.
+    """
+    try:
+        client = _get_client()
+        orgs_info = []
+        archive_count = 0
+        for org in client.organizations:
+            archives = [fc for fc in org.file_cabinets if not fc.is_basket]
+            archive_count += len(archives)
+            orgs_info.append({
+                "name": org.name,
+                "id": org.id,
+                "archive_count": len(archives),
+            })
+        return {
+            "connected": True,
+            "organizations": orgs_info,
+            "archive_count": archive_count,
+        }
+    except Exception as exc:
+        log.exception("status check failed")
+        return {"connected": False, "error": str(exc)}
+
+
+def main() -> None:
+    """Entry point — run the MCP server over stdio."""
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()