docserve

README

docserve

Self-hosted MCP documentation server. Fetches docs from Git providers, indexes with SQLite FTS5, and serves them to LLM agents via MCP Streamable HTTP.

Features

• Multi-provider: GitHub, Azure DevOps, and Confluence Data Center
• Full-text search: SQLite FTS5 with BM25 ranking and token budgets
• MCP native: Exposes list-libraries, resolve-library, and get-library-docs tools over Streamable HTTP
• Scheduled sync: Cron-based periodic fetching keeps docs up to date
• Per-source proxy routing: Each source can opt in/out of a global HTTP proxy
• Auth via env vars: Credentials are never stored in config files
• Minimal footprint: 3 external dependencies, ~15 MB Docker image on scratch

Quick Start

Binary

Download from GitHub Releases:

# Linux amd64
curl -Lo docserve.tar.gz https://github.com/codanael/docserve/releases/latest/download/docserve_linux_amd64.tar.gz
tar xzf docserve.tar.gz
chmod +x docserve

Debian / Ubuntu

curl -Lo docserve.deb https://github.com/codanael/docserve/releases/latest/download/docserve_<version>_amd64.deb
sudo dpkg -i docserve.deb

RPM (Fedora / RHEL)

curl -Lo docserve.rpm https://github.com/codanael/docserve/releases/latest/download/docserve_<version>_amd64.rpm
sudo rpm -i docserve.rpm

Docker

docker run -v ./docserve.yaml:/etc/docserve/docserve.yaml \
  -p 8080:8080 \
  ghcr.io/codanael/docserve serve --config /etc/docserve/docserve.yaml

Configuration

Copy the example config and adjust:

cp docserve.example.yaml docserve.yaml

See docserve.example.yaml for a fully commented reference covering GitHub, Azure DevOps, and Confluence sources.

Credentials are always read from environment variables referenced by name in the config (token_env, username_env, password_env).

Config resolution order

1. --config <path> flag
2. $DOCSERVE_CONFIG environment variable
3. ./docserve.yaml
4. /etc/docserve/docserve.yaml

Usage

# Start the server
docserve serve --config docserve.yaml

# Fetch docs manually
docserve fetch --config docserve.yaml
docserve fetch --config docserve.yaml --source my-docs --force

# List indexed libraries
docserve list --config docserve.yaml

# Search docs from the CLI
docserve search --config docserve.yaml spring-boot "dependency injection"

# Print version
docserve version

MCP Client Configuration

Point your MCP client at the server's /mcp endpoint:

{
  "mcpServers": {
    "docserve": {
      "type": "streamable-http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Health Checks

• GET /healthz -- liveness probe, always returns 200 ok
• GET /readyz -- readiness probe, returns 200 ready once at least one library is indexed

Systemd

The .deb and .rpm packages install a systemd service file. After installing:

# Edit config
sudo cp /etc/docserve/docserve.example.yaml /etc/docserve/docserve.yaml
sudo vim /etc/docserve/docserve.yaml

# Add credentials
sudo vim /etc/docserve/docserve.env   # e.g. GITHUB_TOKEN=ghp_...

# Enable and start
sudo systemctl enable --now docserve
sudo journalctl -fu docserve

Building from Source

make build    # produces bin/docserve
make test     # unit tests
make lint     # golangci-lint

Requires Go 1.22+ and CGO_ENABLED=0 (pure Go SQLite via modernc.org/sqlite).

Verifying Releases

All release checksums are signed with cosign using keyless signing via GitHub Actions OIDC.

Verify checksum signature

# Download the release artifacts
curl -LO https://github.com/codanael/docserve/releases/download/v1.0.0/checksums.txt
curl -LO https://github.com/codanael/docserve/releases/download/v1.0.0/checksums.txt.sigstore.json

# Verify the signature
cosign verify-blob \
  --bundle checksums.txt.sigstore.json \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp 'https://github\.com/codanael/docserve/\.github/workflows/release\.yaml' \
  checksums.txt

# Then verify the tarball against the checksums
sha256sum -c checksums.txt --ignore-missing

Verify Docker image

cosign verify \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp 'https://github\.com/codanael/docserve/\.github/workflows/release\.yaml' \
  ghcr.io/codanael/docserve:v1.0.0

SBOM

Each release archive includes an SBOM in SPDX JSON format (*.sbom.json), generated by syft.

License

MIT