Knowledge Base

The OpalServe knowledge base lets you upload engineering documentation that AI tools can query via MCP. Instead of each developer copy-pasting context into their prompts, you upload it once and every AI tool on the team can find it.

Why a Knowledge Base?

AI coding tools are powerful, but they lack your team's specific context:

How your deployment pipeline works
Your database schema and naming conventions
Incident response procedures
Architecture decisions and trade-offs
Onboarding checklists and team processes

The knowledge base solves this by making your documentation searchable through the MCP protocol. When a developer asks their AI tool "how do we deploy to production?", the tool can query OpalServe's knowledge base and get your team's actual deployment docs.

Adding Documents

Via CLI

bash

# Add a single file
opalserve context add ./docs/architecture.md

# Add with metadata
opalserve context add ./docs/deploy-guide.md \
  --title "Deployment Guide" \
  --tags ops,deployment

# Add an entire directory
opalserve context add ./docs/ \
  --pattern "*.md" \
  --recursive

# Add from a URL (downloads and indexes)
opalserve context add https://wiki.company.com/api/export/runbook.md \
  --title "Incident Runbook" \
  --tags ops,incidents

Via HTTP API

bash

curl -X POST http://localhost:3456/api/v1/context \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Database Schema",
    "content": "# Users Table\n\n| Column | Type | Description |\n...",
    "tags": ["database", "schema"]
  }'

Via the Dashboard

Navigate to the Knowledge Base section in the admin dashboard. Drag and drop files or paste content directly.

Searching the Knowledge Base

CLI

bash

opalserve context search "deployment process"
opalserve context search "database migration" --limit 5 --tags database

Example output:

  Search results for "deployment process" (3 matches)

  [0.92] Deployment Guide
         Tags: ops, deployment
         "To deploy to production, merge to main and the CI pipeline will..."

  [0.81] Release Checklist
         Tags: ops, releases
         "Before each release, ensure all staging tests pass and..."

  [0.74] Incident Runbook
         Tags: ops, incidents
         "If a deployment fails, roll back using..."

HTTP API

bash

curl "http://localhost:3456/api/v1/context/search?q=deployment+process&limit=5" \
  -H "Authorization: Bearer $TOKEN"

How AI Tools Access It

When OpalServe runs as an MCP gateway, it exposes a opalserve_context_search tool that any MCP client can call:

Tool: opalserve_context_search
Input: { "query": "how do we deploy to production" }
Output: Relevant document chunks with titles and scores

This means when a developer using Claude, Cursor, or any MCP-compatible tool asks a question about your team's processes, the AI can automatically search your knowledge base and include the relevant documentation in its response.

MCP Client Configuration

No special configuration is needed on the client side. If the developer is connected to OpalServe (either via team sync or direct MCP connection), the context search tool is automatically available.

json

{
  "mcpServers": {
    "opalserve": {
      "command": "opalserve",
      "args": ["start", "--mcp"]
    }
  }
}

The AI tool will see opalserve_context_search in its available tools and can use it whenever context from your documentation would be helpful.

Managing Documents

List all documents

bash

opalserve context list
opalserve context list --tags database

  Knowledge Base (12 documents)

  ID              Title                    Tags              Size     Updated
  doc_a1b2c3      Deployment Guide         ops, deployment   4.2 KB   2h ago
  doc_d4e5f6      Database Schema          database, schema  8.1 KB   1d ago
  doc_g7h8i9      Incident Runbook         ops, incidents    3.7 KB   3d ago
  ...

Remove documents

bash

# Remove by ID
opalserve context remove doc_a1b2c3

# Remove all documents with a tag
opalserve context remove --all --tags deprecated

Update documents

To update a document, add it again with the same title. OpalServe will replace the existing version:

bash

# Update the deployment guide
opalserve context add ./docs/deploy-guide.md \
  --title "Deployment Guide" \
  --tags ops,deployment
# Replaces the existing document with this title

How Indexing Works

When you add a document, OpalServe:

Parses the document (Markdown, plain text, or HTML)
Chunks it into segments (default: 512 tokens with 64-token overlap)
Indexes each chunk in the SQLite FTS5 full-text search engine
Stores the original document for retrieval

When a search query comes in, OpalServe:

Runs the query against the FTS5 index
Ranks results by relevance score
Returns the top matching chunks with their parent document metadata

Best Practices

What to include

Architecture docs — system diagrams, service maps, data flow
Runbooks — incident response, deployment procedures, rollback steps
Style guides — code conventions, naming rules, PR templates
Onboarding docs — setup instructions, who owns what, key links
ADRs — architecture decision records with context and reasoning
API docs — internal API contracts, endpoint reference
Database schema — table descriptions, relationships, migration history

What not to include

Secrets — API keys, passwords, certificates (use environment variables)
Large binary files — images, videos, compiled artifacts
Auto-generated docs — JSDoc output, Swagger specs (too noisy, changes too often)
Highly volatile content — anything that changes multiple times per day

Organization tips

Use tags consistently

Establish a tagging convention early. For example:

ops for operational docs
database for schema and migration docs
api for API reference
onboarding for new developer docs
arch for architecture decisions

Keep documents focused

Smaller, focused documents work better than large monolithic ones. A 500-word deployment guide will rank higher in search results than a 10,000-word "everything about ops" document.

Automate updates

Use a CI/CD step to sync your docs directory to the knowledge base whenever your documentation repo changes:

bash

# In your CI pipeline
opalserve login $OPALSERVE_URL --api-key $OPALSERVE_API_KEY
opalserve context add ./docs/ --pattern "*.md" --recursive

Configuration

Knowledge base settings in your config file:

json

{
  "knowledgeBase": {
    "enabled": true,
    "maxDocumentSize": 1048576,
    "maxDocuments": 1000,
    "chunkSize": 512,
    "chunkOverlap": 64
  }
}

Field	Type	Default	Description
`enabled`	`boolean`	`true`	Enable/disable the knowledge base
`maxDocumentSize`	`number`	`1048576`	Max single document size in bytes (1MB)
`maxDocuments`	`number`	`1000`	Maximum number of documents
`chunkSize`	`number`	`512`	Token count per chunk
`chunkOverlap`	`number`	`64`	Overlap between adjacent chunks

Knowledge Base ​

Why a Knowledge Base? ​

Adding Documents ​

Via CLI ​

Via HTTP API ​

Via the Dashboard ​

Searching the Knowledge Base ​

CLI ​

HTTP API ​

How AI Tools Access It ​

MCP Client Configuration ​

Managing Documents ​

List all documents ​

Remove documents ​

Update documents ​

How Indexing Works ​

Best Practices ​

What to include ​

What not to include ​

Organization tips ​

Configuration ​

Knowledge Base

Why a Knowledge Base?

Adding Documents

Via CLI

Via HTTP API

Via the Dashboard

Searching the Knowledge Base

CLI

HTTP API

How AI Tools Access It

MCP Client Configuration

Managing Documents

List all documents

Remove documents

Update documents

How Indexing Works

Best Practices

What to include

What not to include

Organization tips

Configuration