dms-mcp-server

Read-only Model Context Protocol server for DMS repositories exposed by dms-provider-bridge. The MCP server never receives DMS usernames, passwords or tokens. It forwards only the connection-owned credential_id reference and leaves credential resolution to the bridge.

The server uses the official Python MCP SDK v2 with Streamable HTTP. The server supports stateless HTTP so a long-running DMS operation does not block independent MCP clients. Existing calls remain backward compatible; search_items adds the optional search_mode parameter.

MVP tools

• bridge_health

• list_connections

• list_items

• search_items

• search_metadata

• open_share_url

• get_item_info

• read_document

All DMS paths use connection:/path. The server intentionally has no upload, move, copy, mkdir or delete tools.

open_share_url accepts an Alfresco-compatible shared URL, resolves its exact connection:/path, returns item metadata and lists the contents when the URL targets a folder. eDoCat DIR-... links are resolved through their same-host redirect to the underlying Alfresco document-library path.

Related MCP server: FileManager MCP Server

Architecture

MCP client --HTTP--> dms-mcp-server --HTTP--> dms-provider-bridge --> DMS
                                                       |
                                                       +--> credential resolution

For a connection path, the MCP server reads the connection auth contract from the bridge and passes only its credential_id reference back to the bridge operation. The bridge owns resolution and use of DMS secrets. Secrets never enter the MCP process, tool results or MCP configuration.

Configuration

Runtime data lives in config/mcp.json, separately from application code:

{
  "bridge": {
    "url": "http://127.0.0.1:8765",
    "minimumVersion": "0.2.0"
  },
  "server": {
    "host": "127.0.0.1",
    "port": 8781,
    "path": "/mcp",
    "statelessHttp": true
  },
  "runtime": {
    "timeoutSeconds": 30,
    "maxDocumentBytes": 1048576
  },
  "debug": {
    "enable": true,
    "path": "%APPDATA%\\DMS MCP\\logs",
    "loggerLevels": {
      "httpx": "WARNING",
      "httpcore": "WARNING"
    }
  }
}

server.statelessHttp is enabled by default for the SDK v2 runtime. Logger levels are data-driven; the defaults keep low-level HTTP transport chatter out of Laděnka while preserving MCP tool and operation events.

The service always writes UTF-8 operational events to mcp.log. When debug.enable is true, detailed events are also written to mcp-debug.log in the configured directory. Tool logs never contain credentials or downloaded document content.

The machine configuration provides the required base document. Optional user overrides are loaded from %APPDATA%\\DMS MCP\\config\\mcp.local.json and merged over that base. Set DMS_MCP_MACHINE_CONFIG_DIR or DMS_MCP_USER_CONFIG_DIR to use other config directories.

The distributed application keeps config/mcp.json beside the application, not inside the Python package. A packaged executable therefore has this layout:

dms-mcp-server/
|-- dms-mcp-server.exe
`-- config/
    `-- mcp.json

User overrides in %APPDATA%\\DMS MCP\\config\\mcp.local.json are merged on top of that default. Environment variables have the highest priority. A wheel is only an installer input: a bare pip install is not a complete application deployment unless the installer also places config/mcp.json beside the application or sets DMS_MCP_MACHINE_CONFIG_DIR.

Environment variables remain available as final runtime overrides:

Credential IDs are owned by bridge connection configuration and are never selected by the AI or duplicated in MCP configuration.

The Bridge HTTP client ignores system proxy environment variables. This keeps local Bridge traffic on its configured direct connection instead of routing it through HTTP_PROXY or ALL_PROXY.

Development

python -m venv .venv
.\.venv\Scripts\pip.exe install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest

Run the MCP HTTP service:

.\.venv\Scripts\dms-mcp-server.exe

The default endpoint is http://127.0.0.1:8781/mcp. Diagnostic scripts invoke the same executable with the explicit --stdio compatibility switch.

The HTTP listener remains localhost-only. If a trusted loopback reverse proxy such as Tailscale Serve preserves an external Host header, opt in to that single exact host in the user-local mcp.local.json:

{
  "server": {
    "allowedHosts": ["vfs-node.example.ts.net:8443"]
  }
}

Localhost hosts remain allowed automatically. Wildcards are rejected so this setting cannot silently disable the MCP SDK's DNS-rebinding protection.

Run the read-only live smoke test while the bridge and its configured credential resolution service are running:

.\.venv\Scripts\python.exe scripts\run_live_smoke.py alfresco edocat

The smoke test exercises the original browsing and document tools. It prints document metadata, size and SHA-256 only; document content is never printed.

Display a bounded tree of DMS folders and files through the MCP server:

.\.venv\Scripts\python.exe scripts\debug_dms.py alfresco edocat --max-depth 2

Optionally verify one document without printing its content:

.\.venv\Scripts\python.exe scripts\debug_dms.py alfresco `
  --document "alfresco:/Shared/report.docx"

The debug command prints names and available item metadata. Document verification prints only MIME type, byte size and SHA-256. Traversal is bounded by --max-depth, --max-directories and --max-items.

Run the local web inspector to see every MCP request and response side by side:

.\.venv\Scripts\python.exe scripts\web_debug.py

Then open the address configured by inspector.host and inspector.port in config/mcp.json (default http://127.0.0.1:8780). Command-line --host and --port values may temporarily override the JSON configuration. The inspector exposes the original six browsing and document tools and binds only to localhost; open_share_url remains available to MCP clients without adding another diagnostic UI control. Its Search control calls native provider search below the selected DMS path. For read_document, it displays MIME type, byte size and SHA-256 of the original bytes while omitting document content. Switch between the raw MCP Response and a clickable UI View for connections, folders, files and metadata; .. navigates to the parent folder. Its API accepts only local Host/Origin values and JSON requests.

Example HTTP MCP client configuration:

{
  "mcpServers": {
    "dms": { "url": "http://127.0.0.1:8781/mcp" }
  }
}