docs-site.md

Overview

This repository is the single source of truth for Falcon MCP documentation. The docs/ directory contains standard GitHub-flavored Markdown with HTML comment annotations that an external documentation site uses to build the published pages. The annotations are invisible when rendered on GitHub.

For the full annotation reference, see Content Tag Guide.

Directory Structure

docs/
  getting-started/         # Hand-authored: installation, credentials, config, quickstart
  usage/                   # Hand-authored: CLI, transports, editor integration, flight control
  modules/                 # AUTO-GENERATED: one page per Python module + overview
  deployment/              # Hand-authored: Docker, Amazon Bedrock, Google Cloud
  development/             # Hand-authored: contributing, module dev, resource dev, testing, this guide
  examples/                # Hand-authored: basic usage, MCP config
  changelog.md             # AUTO-GENERATED: copied from root CHANGELOG.md

Governance files (CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md) live in .github/, not in docs/.

Page Metadata

Every content file starts with HTML comment annotations that the external site uses for page metadata and rendering. These are invisible on GitHub.

Required tags at the top of every file:

<!-- meta:title Page Title -->
<!-- meta:description A short description of the page. -->
<!-- meta:section getting-started -->
<!-- meta:link-base /falcon-mcp/ -->

Optional tags:

<!-- frontmatter:sidebar order:10 -->

Tag	Purpose
meta:title	Page title used on the documentation site
meta:description	Page description used on the documentation site
meta:section	Subdirectory this page belongs to (getting-started, usage, modules, deployment, development, examples)
meta:link-base	URL prefix for internal links (typically /falcon-mcp/)
frontmatter:sidebar	Sidebar ordering (e.g., order:10)

Admonitions

Use GitHub-flavored admonition syntax:

> [!NOTE]
> This is a note.

> [!CAUTION]
> This is a caution.

> [!TIP]
> This is a tip.

These render natively on GitHub and get converted to Starlight ::: directives by the external site's build process.

Auto-Generated Content

Module Pages

The script scripts/generate_module_docs.py introspects the Python source in falcon_mcp/modules/ and produces one page per module under docs/modules/, each containing:

• Title and description (derived from the module file's docstring)
• API scopes (derived from operation names found in source code)
• Tools with docstrings, per-tool scopes, annotations (read-only / mutating / destructive), and example prompts
• Resources with URIs and descriptions

Module Overview Page

A summary table (docs/modules/overview.md) listing all modules with their API scopes and descriptions.

Changelog

The root CHANGELOG.md is copied with annotation tags prepended. This happens in scripts/build_docs.sh.

How Titles and Descriptions Are Derived

The generator reads each module file's docstring:

• Title: Extracted from the first line by stripping the module for Falcon MCP Server. suffix
• Description: Extracted from the second paragraph's first sentence, stripping the common This module provides tools for ... prefix

To override either, add an entry to MODULE_METADATA in scripts/generate_module_docs.py.

Adding a New Module to Docs

Nothing is needed. The generator uses pkgutil.iter_modules() to discover all Python modules in falcon_mcp/modules/ automatically. Any new module file is picked up on the next build.

If you need a custom title, slug, or description, add an entry to MODULE_METADATA in scripts/generate_module_docs.py:

MODULE_METADATA: dict[str, dict[str, Any]] = {
    "mymodule": {
        "title": "My Custom Title",      # optional
        "slug": "my-module",             # optional (defaults to module key)
        "description": "Custom desc.",   # optional (defaults to docstring-derived)
    },
}

To add example prompts for a tool, add entries to TOOL_EXAMPLES:

TOOL_EXAMPLES: dict[str, list[str]] = {
    "falcon_my_tool": [
        "Example prompt for the tool",
    ],
}

Adding or Editing Content Pages

Content pages live under docs/. Each .md file needs annotation tags at the top (see Page Metadata above). The external site handles sidebar configuration. Use the frontmatter:sidebar tag to control page ordering within each section.

The modules/ directory is auto-generated; pages there don't need manual creation.

Local Workflow

Generate module docs, copy the changelog, and lint all markdown:

bash scripts/build_docs.sh

This runs:

1. uv run python scripts/generate_module_docs.py — regenerates docs/modules/
2. Copies CHANGELOG.md with annotation tags to docs/changelog.md
3. Runs markdownlint on all files under docs/

You can also run the generation script directly:

uv run python scripts/generate_module_docs.py

CI Freshness Check

The .github/workflows/docs-check.yml workflow ensures module documentation stays in sync with the code. On pull requests that touch falcon_mcp/, scripts/generate_module_docs.py, or docs/, the workflow:

1. Runs uv run python scripts/generate_module_docs.py
2. Checks git diff --exit-code docs/modules/

If the committed module docs differ from what the script produces, the check fails. This prevents stale documentation from being merged.

After adding or modifying a module, always regenerate and commit the updated docs:

uv run python scripts/generate_module_docs.py
git add docs/modules/