Database MCP — Docker build & troubleshooting

Companion to the user manual. Covers building FreePeak/db-mcp-server from source (SQLite / Oracle on main), common failures, and how to use asb_db_* tools through this app’s MCP endpoint.

1. Why build your own image?

Docker Hub freepeak/db-mcp-server:v1.8.0 and :latest currently share the same digest and are built from a tree whose go.mod includes only MySQL and PostgreSQL. SQLite is not in that build, so the server falls back to mock_* tools. The main branch on GitHub adds SQLite, Oracle, etc.; building from that source produces a usable image for SQLite.

2. Build script (this repository)

From the automation_skill_builder root:

chmod +x scripts/build_db_mcp_server_docker.sh
./scripts/build_db_mcp_server_docker.sh

Common environment variables:

After a successful build, point this application at the image and restart the server:

export DB_MCP_SERVER_RUNTIME_IMAGE=local/db-mcp-server:myfork

3. Docker Hub timeout (auth.docker.io / i/o timeout)

Symptoms: failed to fetch oauth token, dial tcp …:443: i/o timeout when pulling golang:1.24-alpine or alpine:latest.

• Use VPN or a network path that reaches docker.io.
• Docker Desktop → Settings → Docker Engine → add registry-mirrors (use mirrors valid in your region), then Apply & Restart.
• Offline transfer: on a machine that can reach Docker Hub:

  docker pull golang:1.24-alpine
  docker pull alpine:latest
  docker save golang:1.24-alpine alpine:latest -o bases.tar

  Copy bases.tar here, then docker load -i bases.tar, and run the build script again.

The script pre-pulls base images (parsed from the upstream Dockerfile) so failures surface before the full build.

4. GitHub zip download hangs

Symptoms: log stops at Downloading archive... with no progress.

• Use VPN or download the same URL in a browser: https://github.com/<owner>/db-mcp-server/archive/refs/heads/<branch>.zip
• Then run with DB_MCP_SOURCE_ZIP=/path/to/archive.zip (other env vars unchanged).

The script uses curl with connect timeout, max time, retries, and a progress bar. A stuck download usually means GitHub is unreachable or very slow.

5. macOS: failed to xattr … operation not permitted

Unzipping on macOS can create AppleDouble files (._*) and extended attributes; Docker Desktop may error when sending the build context.

The script clears xattrs and deletes ._* / .DS_Store under build/db_mcp_docker_build after extract. If problems persist, grant Full Disk Access to Docker Desktop (macOS Privacy settings).

6. SQLite file on the host (Docker stdio)

When this app starts db-mcp-server via Docker, it bind-mounts the parent directory of your active connections JSON at /asb-mcp-data (read-write), unless DB_MCP_SERVER_DOCKER_DATA_DIR overrides it.

Use an in-container path such as:

"database_path": "/asb-mcp-data/db_mcp_local.sqlite"

See manual §5.1 for details.

7. Getting Database MCP tools via MCP

This application exposes FastAPI routes derived from OpenAPI as MCP tools (FastApiMCP). Dynamic db-mcp-server tools appear with the prefix asb_db_ (see TOOL_NAME_PREFIX in the codebase).

7.1 Connect your MCP client

• Start the automation server without --no-mcp.
• Use the streamable HTTP base (recommended for Claude Desktop and similar): http://127.0.0.1:8800/mcp-http (replace host/port if you changed AUTOMATION_SERVICE_PORT).
• Legacy SSE: http://127.0.0.1:8800/mcp — follow your client’s docs.

7.2 List tools and filter asb_db_*

OpenAPI (browser or curl):

curl -sS http://127.0.0.1:8800/openapi.json | python3 -c "
import json, sys
d = json.load(sys.stdin)
for path, methods in d.get('paths', {}).items():
    for m, v in methods.items():
        if not isinstance(v, dict):
            continue
        oid = v.get('operationId') or ''
        if oid.startswith('asb_db'):
            print(oid, m.upper(), path)
"

Settings API (includes exposure flags and paths):

curl -sS http://127.0.0.1:8800/api/settings/mcp_tools | python3 -c "
import json, sys
j = json.load(sys.stdin)
for t in j.get('tools', []):
    oid = t.get('operation_id', '')
    if oid.startswith('asb_db'):
        print(oid, t.get('method'), t.get('path'))
"

If a service API key protects some routes, add Authorization: Bearer … where required (MCP endpoints are usually unaffected).

7.3 Tool naming

Upstream generates names like query_<connection_id>. This app registers them as asb_db_query_<connection_id> (and similarly for execute_, schema_, etc.). If you only see asb_db_mock_*, the server did not load real connections — see §1 and ensure your image and JSON match.

7.4 Tool visibility

Individual tools can be hidden in the UI under MCP & server utilities → Tool visibility (mcp_tools_visibility.json). If a tool is missing from the client, check it is not disabled there.