sha1n/mcp-acdc-server repository overview

⁠mcp-acdc-server

Agent Content Discovery Companion (ACDC) MCP Server

A Model Context Protocol (MCP) server that gives AI agents searchable access to your Markdown content. Full-text search powered by Bleve⁠, dual transport (stdio/SSE), and optional authentication.

📦 Source & full docs: github.com/sha1n/mcp-acdc-server⁠

⁠Quick Start

SSE (HTTP service):

docker run -d --name acdc \
  -p 8080:8080 \
  -e ACDC_MCP_TRANSPORT=sse \
  -v "$(pwd)/content:/app/content:ro" \
  sha1n/mcp-acdc-server:latest

curl http://localhost:8080/health   # -> 200 OK

stdio (agent launches the process):

docker run -i --rm \
  -v "$(pwd)/content:/app/content:ro" \
  sha1n/mcp-acdc-server:latest

⁠Zero-config content

No manifest required. Mount any repository and the server indexes README.md and docs/**/*.md using built-in server identity and instructions:

docker run -d -p 8080:8080 -e ACDC_MCP_TRANSPORT=sse \
  -v "$(pwd):/app/content:ro" sha1n/mcp-acdc-server:latest

Add a .acdc/config.yaml to the content root to override the defaults — customize server identity and instructions, and add an index block to select Markdown by glob pattern. See the Authoring Resources Guide⁠.

⁠Image Details

Built-in environment defaults: ACDC_MCP_CONTENT_DIR=/app/content, ACDC_MCP_HOST=0.0.0.0, ACDC_MCP_PORT=8080.

⁠Tags

⁠Configuration

Every setting is available as a CLI flag or an ACDC_MCP_* environment variable. Environment variables are the natural fit for containers.

⁠Server

⁠Search

⁠Authentication (SSE only)

docker run -d -p 8080:8080 \
  -e ACDC_MCP_TRANSPORT=sse \
  -e ACDC_MCP_AUTH_TYPE=apikey \
  -e ACDC_MCP_AUTH_API_KEYS=key1,key2 \
  -v "$(pwd)/content:/app/content:ro" \
  sha1n/mcp-acdc-server:latest

Startup fails fast on contradictory auth configuration — for example basic without credentials, or basic combined with API keys.

Full reference: Configuration Guide⁠.

⁠Health Check

In SSE mode the server exposes an unauthenticated /health endpoint returning 200 OK, suitable for Kubernetes probes and Compose health checks:

livenessProbe:
  httpGet:
    path: /health
    port: 8080
readinessProbe:
  httpGet:
    path: /health
    port: 8080

⁠Docker Compose

services:
  mcp-acdc-server:
    image: sha1n/mcp-acdc-server:latest
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      - ACDC_MCP_CONTENT_DIR=/app/content
      - ACDC_MCP_TRANSPORT=sse
      - ACDC_MCP_HOST=0.0.0.0
      - ACDC_MCP_PORT=8080
    volumes:
      - ./content:/app/content:ro
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:8080/health"]
      interval: 30s
      timeout: 3s
      start_period: 5s
      retries: 3

Ready-made deployment and content-configuration examples live in examples/⁠:

• Local Content⁠ — direct bind mount, for rapid iteration.
• Image Content⁠ — production-like init-container pattern that ships content as its own image.
• Repository Docs⁠ — chunk indexing over an existing repository's docs/ directory.

⁠Connecting an Agent

Claude Code:

SSE:

claude mcp add --scope user --transport sse acdc http://<host>:8080/sse

stdio (the agent launches the container):

claude mcp add --scope user --transport stdio acdc -- docker run -i --rm -v "$(pwd)/content:/app/content:ro" sha1n/mcp-acdc-server:latest

Gemini CLI:

SSE:

gemini mcp add --scope user --transport sse --trust acdc http://<host>:8080/sse

stdio (the agent launches the container):

gemini mcp add --scope user --transport stdio --trust acdc docker -- run -i --rm -v "$(pwd)/content:/app/content:ro" sha1n/mcp-acdc-server:latest

For authenticated servers, supply the Authorization or X-API-Key header through your client's configuration.

⁠Features

• Full-text search — stemming, bounded fuzzy matching, and per-field boosting
• Dynamic resource discovery — content directories scanned automatically
• Dynamic prompt discovery — prompt templates scanned automatically
• Content refresh — search, read, and resource reads re-check the content root (debounced to once every 2s) and rebuild in place, so mid-session edits appear without a restart
• MCP compliant — works with any MCP-capable agent
• Dual transport — stdio for local agents, sse for remote/containerized deployments
• Optional authentication — basic auth or API keys

⁠License

Apache-2.0 — see LICENSE⁠.