odd-docs

License Notice: This project is source-available under the Odd Essentials License (OEL). Commercial use requires a separate license. See LICENSE for full terms.

odd-docs is a documentation generation utility within the oddessentials-mcp ecosystem. It produces deterministic, structured documentation for MCP-compatible tools, servers, or repositories by inspecting manifests, schemas, and related metadata.

It can be used in two distinct execution modes:

1. Manual CLI execution
2. MCP-managed execution (via an MCP host such as oddessentials-mcp)

Although both modes generate documentation automatically, they differ fundamentally in execution ownership, filesystem control, and persistence guarantees. This README documents both paths explicitly.

Requirements

• Node.js ≥22.0.0 (see .nvmrc)
• npm or npx

Quick Start

# Show version
npx @oddessentials/odd-docs --version

# Generate documentation for the current directory
npx @oddessentials/odd-docs generate .

# Validate without generating
npx @oddessentials/odd-docs validate .

# Start a local preview server
npx @oddessentials/odd-docs serve .

What odd-docs does

At a high level, odd-docs:

• Reads MCP-style manifests and schema definitions
• Builds an internal documentation representation
• Emits human-readable documentation (Markdown and/or HTML)
• Optionally validates documentation inputs
• Can serve generated documentation locally for inspection

odd-docs is intentionally non-interactive and deterministic: given the same inputs, it produces the same outputs.

Installation (manual usage)

For standalone usage, install via npm:

npm install -g @oddessentials/odd-docs

Or run without installing:

npx @oddessentials/odd-docs --help

Global Options

odd-docs --version, -V   # Show version number
odd-docs --help          # Show help for any command

CLI Commands

Command structure

odd-docs <command> <path> [options]

<path> is typically a repository root containing:

• an MCP-compatible manifest
• associated schema files
• optional descriptive markdown

generate

Generate documentation for an MCP repository.

odd-docs generate <repo-path> [options]

Options:

| Option | Default | Description | | ----------------------- | ---------------- | -------------------------------------- | | -f, --format <format> | md | Output format: md, html, or both | | -o, --output <dir> | docs/generated | Output directory for generated files | | --introspect <url> | — | MCP server URL for live introspection |

Example:

odd-docs generate . --format both --output docs/generated

Outputs:

• One or more .md and/or .html files
• A machine-readable intermediate representation (IR) JSON file

Exit codes:

• 0 — Success
• 1 — Error (missing manifest, invalid schema, etc.)

When run manually, all generated files persist on disk until you remove them.

validate

Validate documentation inputs without writing output files.

odd-docs validate <repo-path> [options]

Options:

| Option | Description | | -------------- | --------------------------------------------- | | -s, --strict | Fail on unknown safety-affecting capabilities |

Validation checks:

• Required manifest fields
• Schema presence and consistency
• Capability declarations
• Structural correctness

Exit codes:

• 0 — Validation passed
• 1 — Validation failed or error encountered

Suitable for CI pipelines.

serve

Start a local development server for generated documentation.

odd-docs serve <repo-path> [options]

Options:

| Option | Default | Description | | -------------------------- | ---------------- | --------------------------------------------------------------- | | -p, --port <port> | 3000 | Port to listen on | | -H, --host <host> | localhost | Host to bind (localhost for safety) | | -o, --output <dir> | docs/generated | Documentation output directory | | --no-watch | — | Disable file watching | | --watch-mode <mode> | auto | Watch mode: auto or poll (use poll for Docker/NFS) | | --reload <mode> | ws | Reload mechanism: ws, sse, poll, none | | --no-open | — | Do not open browser on start | | --introspect <target> | — | MCP target: http://host:port or stdio:<cmd> | | --enable-mutations | — | Enable mutation API endpoints (requires token) | | --mutation-token <token> | — | Token for mutation endpoints (or ODD_DOCS_MUTATION_TOKEN env) |

Behavior:

• Generates documentation if it does not already exist
• Starts a local HTTP server for viewing the docs
• Watches source files and regenerates on change (unless --no-watch)
• Auto-switches to SSE for non-localhost bindings (safer for K8s)

Exit codes:

• 0 — Clean shutdown (SIGINT/SIGTERM)
• 1 — Error starting server

This mode is intended for local development and inspection.

Temporary directories (manual execution)

When running manually:

• odd-docs operates directly on the filesystem paths you provide
• Output directories are explicitly chosen by the user
• Generated documentation is not automatically deleted

Any temporary directories used internally during processing are scoped to execution only and do not affect output persistence.

Persistence is fully under user control in manual mode.

MCP-managed execution (oddessentials-mcp)

When invoked by an MCP host, odd-docs is not run directly by the user. Instead:

• The MCP host launches odd-docs as a managed tool
• Inputs are staged into an isolated workspace
• Outputs are collected as MCP artifacts
• Execution occurs in a sandboxed environment

This execution model intentionally restricts filesystem access and lifetime.

Temporary directories (MCP-managed execution)

When run under MCP control:

• A temporary working directory is created by the MCP host
• Repository files are copied or mounted into this directory
• Generated documentation is written inside this directory
• The directory is deleted immediately after execution completes

Persistence warning

When executed via MCP:

• The temporary directory cannot be persisted
• There is no supported flag or configuration to retain it
• Directory lifecycle is fully owned by the MCP host
• Cleanup occurs even after successful execution

If persistent documentation files are required, they must be:

• Retrieved from MCP artifact outputs, or
• Generated via manual CLI execution

Relying on MCP-managed temporary directories for persistence is unsupported.

Execution model comparison

| Aspect | Manual CLI execution | MCP-managed execution | | ------------------------ | ------------------------ | ---------------------------- | | Who launches the process | User | MCP host | | Filesystem access | User-controlled paths | Isolated temporary workspace | | Output persistence | Persistent | Ephemeral | | Output retrieval | Direct filesystem access | MCP artifacts | | Execution isolation | Minimal | Strong |

Both modes generate documentation automatically. They differ in who owns execution and filesystem lifecycle.

Summary

• odd-docs generates deterministic documentation from MCP metadata
• Manual execution prioritizes direct filesystem access and persistence
• MCP-managed execution prioritizes isolation and controlled lifecycles
• Temporary directories created under MCP control are always ephemeral

Choose the execution mode based on ownership and persistence requirements, not on automation level.

License

This project is source-available under the Odd Essentials License (OEL).

Commercial use is prohibited without a separate license from Odd Essentials, LLC. See LICENSE for full terms.

Resources

• Contributing
• Code of Conduct
• Changelog
• Deployment Guide
• Specification