ai-docs

terrpan/ai-docs

3.1

If you are the rightful owner of ai-docs and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Model Context Protocol (MCP) server is a specialized server designed to facilitate seamless integration with AI tools like GitHub Copilot, enabling efficient access to documentation and resources.

AI-Docs

A playground markdown-based wiki platform with MCP server integration for seamless documentation access through GitHub Copilot in VS Code.

Features

  • 📝 Markdown Wiki: Static site generation using Docusaurus 3.x
  • 🔍 Smart Search: Full-text search across all documentation
  • 🏷️ Organization: Categories and tags for content organization
  • 🔄 Git-Based Workflow: Edit content by pushing markdown files via git
  • 🤖 MCP Integration: Access wiki articles directly in VS Code through GitHub Copilot
  • 🐳 Docker Ready: One-command deployment with Docker Compose

Quick Start

Prerequisites

  • Node.js 20 LTS or higher
  • pnpm 8.x or higher
  • Docker and Docker Compose (for containerized deployment)

Local Development

  1. Clone the repository:

    git clone <repository-url>
cd ai-docs

  2. Install dependencies:

    corepack enable
corepack prepare pnpm@latest --activate
pnpm install

  3. Start the development server:

    pnpm start

    The wiki will be available at http://localhost:3000

Docker Deployment

  1. Build and run with Docker Compose:

    docker compose up --build

  2. Access the wiki:

Project Structure

ai-docs/
├── wiki/                     # Docusaurus wiki application
│   ├── docs/                # Markdown content (wiki pages)
│   ├── src/                 # Custom Docusaurus components
│   ├── static/              # Static assets (images, files)
│   ├── docusaurus.config.ts # Docusaurus configuration
│   ├── sidebars.ts          # Auto-generated sidebar (do not edit manually)
│   ├── generate-sidebars.js # Dynamic sidebar generator
│   ├── standardize-metadata.js # Metadata standardization tool
│   ├── fix-links.js         # Link fixing utility
│   └── package.json         # Wiki dependencies
├── mcp-server/              # MCP server for VS Code integration
│   ├── src/                 # TypeScript source code
│   └── package.json         # MCP server dependencies
├── indexer/                 # Document indexing service
│   ├── indexer.py           # Main indexer script
│   └── requirements.txt     # Python dependencies
├── embedding-service/       # Text embedding service
│   ├── server.py            # FastAPI server
│   └── requirements.txt     # Python dependencies
├── docker-compose.yml       # Multi-service orchestration
├── pnpm-workspace.yaml      # pnpm workspace configuration
└── package.json             # Root workspace scripts

Git-Based Content Workflow

AI-Docs uses a git-based workflow for all content changes. Simply edit markdown files, commit, and push - the site automatically rebuilds.

Basic Workflow

  1. Clone the repository (first time only):

    git clone <repository-url>
cd ai-docs

  2. Create or edit markdown in wiki/docs/ directory:

    # Create a new guide
touch wiki/docs/guides/my-guide.md

# Or edit existing content
vim wiki/docs/guides/existing-guide.md

  3. Add required frontmatter:

    ---
title: My New Guide
description: A step-by-step guide for beginners
category: Guides
tags: [tutorial, beginner, example]
date: 2025-11-14
---

# My New Guide

Your content here...

  4. Commit and push your changes:

    git add wiki/docs/guides/my-guide.md
git commit -m "Add guide for new feature"
git push origin main

  5. Automatic rebuild (Docker deployment only):

    • Git post-receive hook detects wiki/docs/ changes
    • Docker container automatically restarts
    • Sidebar automatically regenerates
    • Site regenerates with new content
    • Timeline: Complete within 30 seconds

  6. Verify your changes:

    # Local dev: http://localhost:3000
# Production: your-wiki-domain.com
open http://localhost:3000

Setup Git Hook (For Production Deployments)

Enable automatic rebuilds on git push:

# Copy post-receive hook to your git repository
cp scripts/post-receive .git/hooks/post-receive

# Make it executable
chmod +x .git/hooks/post-receive

The hook triggers on any push that modifies the wiki/docs/ directory.

Content Organization

Categories (top-level sections):

  • Wiki Docs - Documentation about using this wiki (installation, writing, workflow)
  • Guides - How-to tutorials and step-by-step instructions
  • Reference - API documentation, architecture, configuration
  • Examples - Code samples and templates
  • Blogs - Technical blog posts and articles
  • CI/CD - Pipeline, GitOps, and deployment workflows
  • Cloud - Cloud architecture and AWS patterns
  • Docker - Container best practices and optimization
  • Engineering - Java guidelines, SDLC processes
  • Kubernetes - K8s deployment patterns and best practices
  • Observability - Monitoring, logging, and tracing
  • Onboarding - Engineer onboarding materials
  • Security - Security best practices and guidelines
  • Tech Radar - Technology adoption and recommendations

File Structure:

wiki/docs/
├── wiki-docs/            # Documentation about this wiki
│   ├── intro.md
│   ├── installation.md
│   ├── quickstart.md
│   ├── writing-markdown.md
│   ├── git-workflow.md
│   └── frontmatter-guide.md
├── guides/               # How-to guides
│   ├── mcp-setup.md
│   └── docker-deploy.md
├── reference/            # Technical reference
│   ├── architecture.md
│   └── mcp-tools.md
├── examples/             # Examples
│   ├── basic-page.md
│   └── advanced.md
├── blogs/                # Blog posts
│   ├── index.md
│   └── docker-best-practices.md
├── cicd/                 # CI/CD documentation
├── cloud/                # Cloud architecture
├── docker/               # Docker guides
├── engineering/          # Engineering practices
├── kubernetes/           # Kubernetes guides
├── observability/        # Observability guides
├── onboarding/           # Onboarding materials
├── security/             # Security documentation
└── tech-radar/           # Tech Radar

Page Templates

Use the provided template for consistent structure:

# Copy template for new page
cp wiki/docs/_templates/page-template.md wiki/docs/guides/my-new-page.md

# Edit with your content
code wiki/docs/guides/my-new-page.md

The template includes all required frontmatter fields and common content sections.

Maintenance Scripts

The wiki includes helpful maintenance scripts:

# Standardize metadata across all files
cd wiki && node standardize-metadata.js

# Fix internal links after reorganization
cd wiki && node fix-links.js

# Check for broken links
cd wiki && node check-broken-links.js

Best Practices

  • Descriptive titles: Make titles searchable and clear
  • One-sentence descriptions: Summarize the page purpose
  • 3-5 tags per page: Use common tags consistently
  • Update dates: Change date when making significant edits
  • Test locally: Run pnpm start to preview before pushing
  • Atomic commits: One logical change per commit
  • Clear commit messages: Describe what and why

For detailed instructions, see and

MCP Server Integration

See for instructions on connecting the MCP server to VS Code and GitHub Copilot.

Documentation

Architecture

AI-Docs is a distributed system with multiple services:

Core Services

  1. Docusaurus Wiki (Port 3000)

    • React-based static site generator
    • Serves human-readable documentation

  2. MCP Server (Port 3001)

    • Node.js + TypeScript HTTP server
    • Provides AI-friendly API for GitHub Copilot
    • Query-only mode (stateless)

  3. ChromaDB (Port 8000)

    • Vector database for semantic search
    • Stores 518 chunk embeddings (42 articles)

  4. Embedding Service (Port 8001)

    • FastAPI + sentence-transformers
    • Converts text to 384-dimensional vectors
    • Model: all-MiniLM-L6-v2

  5. Python Indexer (One-time job)

    • Reads markdown files
    • Generates embeddings
    • Populates ChromaDB

Data Flow

Indexing (One-time):

Markdown Files → Indexer → Embedding Service → ChromaDB

Querying (Runtime):

GitHub Copilot → MCP Server → Embedding Service → ChromaDB → Results

For detailed architecture diagrams and service interactions, see .

Technology Stack

Constitution Principles

This project follows the AI-Docs Constitution:

  1. Quick Start Priority: Get running in < 5 minutes with Docker
  2. Simple Documentation: Example-driven with working demos
  3. Minimal Dependencies: Each dependency provides significant value

Contributing

  1. Create a new branch for your feature
  2. Add or edit markdown files in docs/
  3. Test locally with pnpm start
  4. Commit and push your changes
  5. The site will regenerate automatically

License

MIT