Actian MCP Server — Documentation Portal

Built with MkDocs Material · Light/dark theme · Versioned with mike

Repository: https://github.com/ActianCorp/mcp-server-docs
Branch: main

---

About This Repository

This repository contains the MkDocs-based documentation portal for the Actian MCP Server

---

What's Included

Feature	Description
MkDocs Material 9.6+	Modern Material Design theme with light/dark toggle
Navigation	Tabs, sections, breadcrumbs, instant loading, pruning
Search	Enhanced search with highlighting, suggestions, and sharing
Diagrams	Mermaid and PlantUML diagram support
API docs	Swagger UI tag plugin for OpenAPI specs
Versioning	Multi-version support via mike
SEO	Auto-generated meta descriptions, robots.txt, sitemap
Code blocks	Copy button, syntax highlighting, annotations
Custom 404	Branded 404 page
Edit on GitHub	Per-page edit button linking to main branch

---

Project Structure

actian_mcp_server/
├── mkdocs.yml                  # Main MkDocs configuration
├── requirements.txt            # Python dependencies
├── makefile                    # Docker shortcuts
├── docs/                       # All documentation content
│   ├── index.md                # Homepage (landing page)
│   ├── .pages                  # Top-level navigation order
│   ├── robots.txt              # Search engine directives
│   ├── assets/                 # Logos, homepage images, site-wide CSS
│   ├── stylesheets/            # Component CSS (search, DX styles)
│   ├── javascripts/            # Custom JS (search, mermaid)
│   ├── intro/                  # What is MCP? Architecture overview
│   ├── get_started/            # Installation & quickstart
│   ├── develop_with_mcp/       # Tools, Resources, Prompts, Plugins
│   │   ├── tools/              # Defining MCP tools
│   │   ├── resources/          # Defining MCP resources
│   │   ├── prompts/            # Defining MCP prompt templates
│   │   └── plugins/            # Building & registering plugins
│   ├── configuration/          # Server configuration reference
│   ├── deployment/             # Local, Docker, and production deployment
│   └── APIs/                   # API reference documentation
├── theme_overrides/            # Custom theme templates
│   ├── main.html               # Base template (header, scripts)
│   ├── home.html               # Landing page template
│   ├── home-blocks.html        # Landing page hero & content blocks
│   ├── 404.html                # Custom 404 page
│   ├── assets/stylesheets/     # Landing page & theme CSS
│   └── partials/               # Partial templates
├── hooks/                      # MkDocs build hooks
│   └── copy_md_sources.py      # Publishes raw Markdown alongside built HTML
├── utils/                      # Utility scripts (audits, link checks)
└── site/                       # Built output (auto-generated, do not edit)

---

Installation

1. Clone the repository

git clone https://github.com/ActianCorp/mcp-server-docs.git
cd mcp-server-docs
git checkout main

2. Install dependencies

pip install -r requirements.txt

This installs:

Package	Purpose
mkdocs-material	Material Design theme
mike	Documentation versioning
mkdocs-awesome-pages-plugin	Custom navigation ordering
mkdocs-git-revision-date-localized-plugin	"Last updated" dates on pages
mkdocs-minify-plugin	HTML minification for production
mkdocs-swagger-ui-tag	Swagger/OpenAPI rendering
mkdocs-meta-descriptions-plugin	Auto SEO meta descriptions
plantuml-markdown	PlantUML diagram support

---

Running Locally

Option A: mkdocs serve (recommended for authoring)

mkdocs serve

Opens a live-reload development server at http://127.0.0.1:8000. Changes to any file under docs/ are reflected instantly.

Option B: Dirty reload (faster for large sites)

mkdocs serve --dirtyreload

Only rebuilds changed pages — faster during active writing.

Building the Site

mkdocs build

Generates the static site in the site/ directory.

To preview the built output locally:

python -m http.server 8080 --directory site

Then open http://127.0.0.1:8080.

---

Adding Documentation

Step 1: Create a section folder and Markdown files

docs/
├── my_section/
│   ├── index.md            # Section landing page
│   ├── my-guide.md         # A guide page
│   └── images/             # Section-specific images

Step 2: Write your content

Each page can include optional front matter:

---
title: My Page Title
description: A brief description for search engines.
---

# My Page Title

Content supports:
- **Admonitions** — `!!! note`, `!!! warning`, `!!! tip`
- **Code blocks** — syntax highlighting + copy button
- **Mermaid diagrams** — inside ```mermaid``` fenced blocks
- **PlantUML diagrams** — via the `plantuml_markdown` extension
- **Tabbed content** — `=== "Tab 1"` syntax

Step 3: Control navigation order

Create a .pages file in your section folder:

# docs/my_section/.pages
nav:
  - index.md
  - my-guide.md

Step 4: Preview and commit

mkdocs serve              # Preview at http://127.0.0.1:8000
git add .
git commit -m "docs: add my_section"
git push origin <your-branch>

See Contributing below for the full contribution workflow, including how to open a pull request against main.

---

Adding API Documentation

Place your OpenAPI/Swagger JSON spec in docs/APIs/ and create a Markdown file:

---
title: My API
---

# My API

<swagger-ui src="my-api-spec.json"/>

---

Customizing the Theme

Colors and branding

File	What it controls
theme_overrides/assets/stylesheets/actian-landing.css	Landing page, CSS variables, dark mode
docs/assets/stylesheets/style.css	Header, tabs, search bar, general overrides
docs/stylesheets/dx_style.css	Search enhancements, syntax highlighting

Logos and images

• Site logo: Replace docs/assets/dx_logo.png
• Favicon: Replace docs/assets/favicon.png
• Landing page images: Add to docs/assets/homepage-images/

Templates

File	Purpose
theme_overrides/main.html	Header, scripts
theme_overrides/home.html	Landing page layout
theme_overrides/home-blocks.html	Hero banner and content blocks
theme_overrides/404.html	Custom 404 error page

Configuration (mkdocs.yml)

Key sections:

• site_name — Documentation title
• site_url — Production URL -- repo_url — GitHub repo link
• theme.palette — Light/dark mode (light is default)
• theme.features — Navigation behaviour toggles
• plugins — Search, versioning, minification, etc.
• extra_css / extra_javascript — Custom stylesheets and scripts

---

Versioning with Mike

# Deploy current docs as version "1.0" aliased as "latest"
mike deploy --push --update-aliases 1.0 latest

# List all deployed versions
mike list

# Set the default version redirect
mike set-default latest

# Serve versioned docs locally
mike serve

---

Key Commands

Command	Description
mkdocs serve	Start live-reload dev server
mkdocs serve --dirtyreload	Faster dev server (rebuilds only changed pages)
mkdocs build	Build the static site to site/
mkdocs build --strict	Build with strict mode (fail on warnings)
mike deploy <version>	Deploy a versioned build to gh-pages
mike serve	Serve versioned docs locally

---

Useful Resources

• MkDocs Documentation
• Material for MkDocs
• Material Reference
• Awesome Pages Plugin
• mike — Versioning
• Model Context Protocol

---

Contributing

Thank you for helping improve the Actian MCP Server documentation portal. main is the single source of truth for this repository. All contributions are made against main; there is no separate long-lived branch for a given release.

Before you start

• Contributors never run mike. Version deployment (mike deploy, mike set-default, and similar) is handled separately by the documentation maintainers.
• Contributors never edit the site/ directory. It is generated output and is overwritten on every build.
• All content changes belong under docs/. Only touch mkdocs.yml, theme_overrides/, or hooks/ if you are intentionally changing the site's build or theme, and mention that clearly in your pull request.

Local setup

Fork the repository, then follow Installation and Running Locally above to clone your fork, install dependencies, and start the live-reload development server.

Making changes

1. Create a feature branch from main:

   git checkout -b docs/my-update

2. Edit or add Markdown files under docs/. See Adding Documentation above for page structure, front matter, and navigation ordering.

3. Preview your changes with mkdocs serve and confirm the page renders and navigates as expected.

4. Validate the build in strict mode before committing. Strict mode fails on warnings (broken links, missing nav entries, and so on), which is the same check applied before a release build:

   mkdocs build --strict

5. Commit your changes with a docs: prefix:

   git add docs/
   git commit -m "docs: describe your change here"

6. Push your branch and open a pull request targeting main. Describe the change and, if relevant, why it was needed.

Style checklist

Before submitting, check your writing against these rules:

• Use Global English (avoid idioms, culturally specific references, and regional spelling; prefer terms understood by a worldwide audience).
• Follow the Chicago Manual of Style for punctuation, capitalization, and numbers.
• Expand acronyms on first use on a page, followed by the acronym in parentheses, for example: Model Context Protocol (MCP).
• Do not use em dashes or en dashes. Rewrite the sentence, or use a comma, parentheses, or a period instead.
• Use sentence case for headings (capitalize only the first word and proper nouns), not title case.

---