OpenCrane

OpenCrane is a standalone, extensible pipeline for AI-powered documentation search, based on retrieval-augmented generation (RAG) and the Model Context Protocol (MCP). With its command-line interface (CLI), you can do the following:

• Fetch documentation from GitHub.
• Generate llms-full.txt bundles.
• Chunk and embed the bundles.
• Index the embeddings into Milvus.
• Serve the index through an MCP server.

Table of contents

This README covers the following topics:

• Features
• Quick start
• Installation
• Usage
  • CLI
    • init
    • add
    • build
    • fetch
    • llms
    • tokens
    • chunk
    • embed
    • index
    • serve
    • pack
    • inspect
    • visualize
  • Health endpoint
  • Default file and directory names
  • Environment variables
  • Source mapping file
• Extend OpenCrane
  • Extension points
  • Section anchors
  • Section navigation and clause IDs
  • Built-in fence types
  • Built-in YAML tree walkers
  • Write a custom fence type
  • Write a custom YAML tree walker
  • Add custom MCP tools
• Authentication and authorization
• Development
• Credits
• License

Features

OpenCrane provides the following features:

• Flexible RAG pipeline: OpenCrane runs the full flow, or only the steps you need. The full flow is fetch → generate llms-full.txt → chunk → embed → index → serve.
• MCP server: the server exposes search tools that any MCP-compatible client can use, for example Claude or Cursor.
• Extensibility: an OpenCraneConfig subclass adds your own code at the extension points, for example a custom chunking strategy. Built-in fence types insert the content of API and schema files, for example OpenAPI specs, into the documentation bundle.
• Section anchors: each chunk records a section_anchor, so citations link to the exact section of a page ({source_url}#{section_anchor}). Section anchors are on by default. Each project can choose the anchor style or override the anchors.
• Command-line interface: every pipeline step is a subcommand. The CLI works in continuous integration and continuous delivery (CI/CD) pipelines and in projects that don't use Python.

Quick start

To create a project without installing OpenCrane, run the following command:

uvx opencrane init

The command creates the .opencrane/ directory with the project configuration and the container files. It then prompts you to add documentation sources.

To build and serve the index, complete the following steps:

1. Install OpenCrane with the pipeline extra, as described in Installation.
2. Set the GITHUB_TOKEN environment variable to a GitHub API token. The fetch step of opencrane build fails without it, even when no source is a GitHub repository.
3. Run opencrane build.
4. Run opencrane serve.

The MCP server starts and prints the commands that add it to common MCP clients.

Installation

OpenCrane requires Python 3.11 or later. The base package runs the MCP server on an index that is already built. To install only the base package, run the following command:

pip install opencrane

To build an index, install the pipeline extra. The following commands need it:

• build
• fetch
• llms
• chunk
• tokens

To install the pipeline extra, run one of the following commands:

# with pip
pip install 'opencrane[pipeline]'

# with uv
uv pip install 'opencrane[pipeline]'

To run a command with the pipeline extra without installing OpenCrane, use uvx:

uvx --from 'opencrane[pipeline]' opencrane {COMMAND}

Usage

This section is the reference for the OpenCrane CLI and its configuration.

CLI

Each pipeline step and each project task has its own opencrane command. Commands that show [--config {MODULE}:{CLASS}] in their usage line accept the --config flag, which loads a custom OpenCraneConfig subclass. The flag takes one of the following values:

• A module and a class name, for example myproject.config:MyConfig. Python must be able to import the module, for example from an installed package or a directory in PYTHONPATH.
• The path to a Python file that defines a class named Config. If the file does not exist, OpenCrane uses the base configuration and reports no error.

The OPENCRANE_CONFIG environment variable takes the same values. Without the flag and the variable, OpenCrane loads the file that the extensions key in .opencrane/config.yaml names.

Create a project with opencrane init

The opencrane init command creates a new project. It has the following syntax:

opencrane init [--podman] [--force] [--no-add] [--extensions]

The command creates the .opencrane/ directory with the following files:

The command accepts the following flags:

Add documentation sources with opencrane add

The opencrane add command adds documentation sources to .opencrane/config.yaml interactively. Run opencrane init first, because the command needs the .opencrane/ directory. The command has the following syntax:

opencrane add

For each source, the command asks you to choose one of the following kinds of source:

1. GitHub repository: the command asks for the following values:

   • Repository URL
   • Path to the documentation in the repository
   • Published documentation URL, optional
   • Source name
   • Git ref to pin, optional

   The next fetch step downloads the documentation.

2. Existing llms.txt file: the command asks for the following values:

   • Source name
   • URL or local path of the llms-full.txt file
   • Published documentation URL, optional

   The next fetch step downloads or copies the file into .opencrane/llmstxt/{NAME}/llms-full.txt. If a companion llms.txt exists next to the file, the fetch copies it too, so each page gets its own source URL.

After each source, the command asks whether to add another source.

Run the full pipeline with opencrane build

The opencrane build command runs all steps in sequence: fetch → llms → chunk → embed → index.

The command has the following syntax:

opencrane build [--config {MODULE}:{CLASS}] [--sources-dir {PATH}]... [--llmstxt-dir {PATH}]
                [--chunks-file {PATH}] [--embeddings-file {PATH}]

The command accepts the following flags:

The llms step of the build runs without --force. For when to run opencrane llms --force first, see the --force row of opencrane llms.

Fetch documentation from GitHub with opencrane fetch

The opencrane fetch command fetches documentation from GitHub repositories.

The command has the following syntax:

opencrane fetch [--config {MODULE}:{CLASS}] [--org {NAME}] [--source {NAMES}]

The command accepts the following flags:

For details about fetching, see Fetch documentation sources.

Generate llms-full.txt bundles with opencrane llms

The opencrane llms command writes one llms-full.txt file for each source, in .opencrane/llmstxt/{SOURCE}/. It also writes a combined llms-full.txt bundle of all sources in .opencrane/llmstxt/. Next to the bundle, it writes a companion llms.txt index that maps each page title to the page URL. For details, see the llms-full.txt generation guide.

The command has the following syntax:

opencrane llms [--config {MODULE}:{CLASS}] [--sources-dir {PATH}]... [--llmstxt-dir {PATH}] [--force]

The command accepts the following flags:

Count tokens with opencrane tokens

The opencrane tokens command writes a Markdown report with the number of tokens in each llms-full.txt file. Use the report to check how much of a model's context window each bundle takes. The command has the following syntax:

opencrane tokens [--source-dir {PATH}] [--output-file {PATH}]

The command accepts the following flags:

Chunk the documentation with opencrane chunk

The opencrane chunk command splits the documentation into chunks and writes them to .opencrane/chunks.json. It has the following syntax:

opencrane chunk [--config {MODULE}:{CLASS}] [--llmstxt-dir {PATH}] [--chunks-file {PATH}] [--force]

The command reads the combined llms-full.txt and its companion llms.txt index, and assigns each chunk the source_url of its page. For a bundle from an earlier OpenCrane version, which has no index, the command reads the page URLs from the bundle itself.

The command accepts the following flags:

Generate embeddings with opencrane embed

The opencrane embed command generates the vector embeddings for the chunks. It has the following syntax:

opencrane embed [--config {MODULE}:{CLASS}] [--chunks-file {PATH}] [--embeddings-file {PATH}] [--force]

The command accepts the following flags:

Index the embeddings in Milvus with opencrane index

The opencrane index command loads the chunks and their embeddings into Milvus. By default, it reads them from .opencrane/chunks.json and .opencrane/embeddings.json.

The command has the following syntax:

opencrane index [--config {MODULE}:{CLASS}] [--chunks-file {PATH}] [--embeddings-file {PATH}]

The command accepts the following flags:

When the Milvus collection already has rows, the command skips indexing and keeps the existing data. This also applies to the index step of opencrane build, so after a documentation update, the build leaves the old data in Milvus.

To replace the existing data, set DROP_EXISTING=true.

The following command replaces the existing data:

DROP_EXISTING=true opencrane index

Start the MCP server with opencrane serve

The opencrane serve command starts the MCP server. It has the following syntax:

opencrane serve [--config {MODULE}:{CLASS}] [--transport stdio|http]

The --transport flag accepts the following values:

The server always exposes the search_docs and health tools. The following tools appear only when the index contains the chunk types that they read:

• get_list_members
• get_table_members
• get_yaml_definition
• get_section
• get_metadata_schema

For the condition behind each tool, see MCP tools. For the parameters, see the MCP tools reference.

Package the server with opencrane pack

The opencrane pack command packages the built MCP server and its data into a standalone Python package that others can run with uvx. Before you pack, run opencrane build. The command packs .opencrane/milvus.db and .opencrane/chunks.json from these fixed paths. The command has the following syntax:

opencrane pack [--name {NAME}] [--output {PATH}] [--version {VERSION}]

The command accepts the following flags:

To generate a wheel, the command needs the optional build Python package. To install it, run pip install 'opencrane[pack]'.

After you pack, share one of the following commands with the people who use the server:

# From PyPI (after publishing)
claude mcp add {SERVER_NAME} -- uvx {PACKAGE_NAME}

# From GitHub
claude mcp add {SERVER_NAME} -- uvx --from "git+https://github.com/{OWNER}/{PACKAGE_NAME}" {PACKAGE_NAME}

# From local path
claude mcp add {SERVER_NAME} -- uvx --from .opencrane/pack {PACKAGE_NAME}

The generated package includes the Milvus database and the chunks file, so the people you share it with don't need to rebuild anything. The server downloads the embedding model on the first search or health call.

When you pack updated documentation again, raise the version with --version above the previous one. Otherwise, uvx serves the package from its cache instead of pulling the new version.

Open the MCP Inspector with opencrane inspect

The opencrane inspect command opens the MCP Inspector web interface, connected to the server over stdio. Use the MCP Inspector to call the server's tools from a browser and check the results. The command starts the server as a local process, so you can test it before you build a container image. The command has the following syntax:

opencrane inspect [--config {MODULE}:{CLASS}]

The command requires npx, which comes with Node.js. The MCP Inspector serves its web interface on port 6274 and prints the URL to open, with its session token.

Compare a paragraph with the indexed documentation with opencrane visualize

The opencrane visualize command shows how close a paragraph is to the indexed chunks. Use it for the following checks:

• Detect duplicates: if the top neighbor has a very high similarity, the content you are writing might already exist.
• Find the right source: the per-source alignment chart shows which source has the closest existing content.
• Check new documentation: if the neighbors are a random mix of unrelated sources with low similarity, your paragraph does not match any existing documentation.

You can pass the paragraph as text, as a file, or through standard input:

opencrane visualize --text "{PARAGRAPH}"
opencrane visualize --file {PATH_TO_FILE}
echo "{PARAGRAPH}" | opencrane visualize

The command encodes the paragraph the way the server encodes a search query. It then renders an interactive HTML page with the following views side by side:

• Scatter: a projection of the indexed chunks, or of a random sample of them when you set --sample. The new paragraph is a highlighted diamond, and the chart draws a ring around each nearest neighbor.
• Local neighborhood: a projection of only the paragraph and its nearest neighbors. Because the projection uses only these points, the distances between the neighbors are meaningful.
• Per-source alignment: a horizontal bar chart of the highest similarity in each source, with a tick for the mean of its 30 closest chunks. The chart shows which source the paragraph is closest to.

The scatter view uses one of the following dimensionality-reduction methods:

• Principal component analysis (PCA)
• Uniform manifold approximation and projection (UMAP)
• t-distributed stochastic neighbor embedding (t-SNE)

The local neighborhood view always uses PCA.

The following table lists the main flags:

The command requires the optional viz extra. To install it, run the following command:

pip install 'opencrane[viz]'

Health endpoint

The HTTP transport of opencrane serve exposes GET /health for the liveness and readiness probes of a container platform, for example Cloud Run. The endpoint reports the following checks:

• Embedding service and Milvus service state
• Collection statistics, such as the row count
• A test search for one result, with a timeout
• Free memory, read from the cgroup
• Whether the keyword search index, which uses the Best Matching 25 (BM25) ranking function, is already loaded in memory

The overall status is the worst status of the individual checks. The following table lists the statuses:

The following example shows a response with the 200 status code:

{
  "status": "healthy",
  "checks": {
    "embeddings_service": "healthy",
    "milvus_service": "healthy",
    "collection_stats": { "row_count": 1234 },
    "heavy_maps": {
      "keyword_index_resident": true
    },
    "memory": {
      "source": "cgroup_v2",
      "used_bytes": 536870912,
      "limit_bytes": 2147483648,
      "headroom_pct": 75.0,
      "status": "healthy"
    },
    "query_probe": {
      "status": "healthy",
      "latency_ms": 143.7
    }
  }
}

When OpenCrane finds no readable cgroup memory files, for example outside a container, memory.status is unavailable and the response leaves out the byte fields. The health MCP tool returns the same report. To tune the probe and the memory threshold, use the health check environment variables.

To use the endpoint on a container platform, configure the probes as follows:

• Point the liveness and readiness probes at GET /health on port 8000.
• Set the startup or initial delay long enough for the embedding model to load. Until the model loads, /health returns 503 initializing.
• Use a long liveness period, so that the probe does not run a real search every few seconds.

Default file and directory names

To override a default for one run, use the CLI flag. To override it persistently, set the environment variable. A CLI flag takes precedence over the environment variable. The following table lists the default files and directories of the pipeline:

The MCP server also reads the chunks file, for keyword search.

Keep the following variables at their defaults in these cases:

• TARGET_DIR, when you run the llms step without --sources-dir. The step reads the fetched documentation only from .opencrane/sources.
• AI_DOCS_LLMSTXT_DIR, when you use llmstxt sources. The fetch step writes them only to .opencrane/llmstxt.

Environment variables

Environment variables set persistent defaults, for example in a CI/CD pipeline. For the variables that set file paths, see Default file and directory names. The following sections list the other variables.

Variables for all commands

Every opencrane command reads the following variable:

Variables for the fetch step

You need the following variables only if you run the fetch step, directly or through opencrane build:

Variables for the llms step

The llms step, run directly or through opencrane build, reads the following variable:

Variables for the chunk step

The chunk step, run directly or through opencrane build, reads the following variables:

For the PROSE_* variables, see Prose sections.

Variables for the embed step

You need the following variables only if you run the embed step, directly or through opencrane build:

Variables for the index and serve steps

You need the following variables when you load data into Milvus or run the MCP server. OpenCrane supports two Milvus modes:

• Lite mode: the default. Milvus Lite stores the data in a local file at .opencrane/milvus.db and needs no server.
• Server mode: a separate Milvus server. To use it, set MILVUS_HOST and MILVUS_PORT, and leave MILVUS_DB_PATH unset.

When you set MILVUS_DB_PATH, the variable selects the mode, even if MILVUS_HOST is also set. A file path selects Lite mode, and an empty string selects server mode.

The following table lists the variables:

Variables for the HTTP transport

The following variables configure the HTTP transport of opencrane serve:

For PUBLIC_URL and the other authentication variables, see Authentication and authorization.

Variables for the health check

The following variables tune the search probe and the memory threshold of the health endpoint. All of them are optional.

Source mapping file

The source mapping file, .opencrane/config.yaml, lists the documentation sources under the sources: key. The fetch step adds and updates the entries of the repositories that it auto-discovers. You edit the entries that you manage yourself. The same file also holds other project settings, for example section_anchor_style. For the fields of an entry, see Source mapping file.

By default, opencrane fetch pulls from the latest GitHub release of a repository, or from the default branch when the repository has no releases. To pin an entry with manual: true to a specific Git ref instead, set one of the following fields:

• sha: a commit SHA
• tag: a Git tag
• release: the tag name of a GitHub release
• branch: a branch

OpenCrane ignores these fields on entries without manual: true. Set only one of the fields. If you set several, OpenCrane logs a warning and uses the first one in the order of the previous list.

The following example pins a manually managed source to a tag:

sources:
  my-product:
    url: https://github.com/myorg/my-product
    docs_path: docs
    docs_url: https://docs.example.com/my-product
    manual: true
    tag: v2.1.0

Extend OpenCrane

To register extensions for your project, subclass OpenCraneConfig, as in the following example:

# myproject/config.py
from opencrane import OpenCraneConfig
from opencrane.fences import CodeFenceConfig, inline_file
from opencrane.rag.services.yaml_chunker import YamlChunkingStrategy
from opencrane.rag.services.code_chunker import CodeChunkingStrategy
from opencrane.rag.services.table_chunker import TableChunkingStrategy
from opencrane.rag.services.list_chunker import ListChunkingStrategy
from opencrane.rag.services.prose_chunker import ProseChunkingStrategy
from myproject.strategies.custom import CustomChunkingStrategy
from myproject.walkers.terraform import TerraformTreeWalker

class Config(OpenCraneConfig):
    fence_types = {
        **OpenCraneConfig.fence_types,  # keep openapi, asyncapi, crd, json-schema
        "terraform": CodeFenceConfig(fence_type="terraform", handler=inline_file),
    }
    chunking_strategies = [
        YamlChunkingStrategy(),
        CustomChunkingStrategy(),
        CodeChunkingStrategy(),
        TableChunkingStrategy(),
        ListChunkingStrategy(),
        ProseChunkingStrategy(),
    ]
    yaml_tree_walkers = [
        *OpenCraneConfig.yaml_tree_walkers,  # keep CRD, OpenAPI, JSON Schema
        TerraformTreeWalker,
    ]

To use the subclass, pass it to the --config flag:

opencrane build --config myproject.config:Config

Python must be able to import the myproject module, as described in CLI. OpenCrane tries the chunking strategies in list order and uses the first one that matches the content. Put a custom strategy before the general strategies that would otherwise match first.

Extension points

Each extension point is an attribute or a method of OpenCraneConfig. The following table lists the pipeline step that uses each one:

Section anchors

Each chunk from a Markdown section records a section_anchor in its metadata. The value is the in-page anchor of the nearest heading above the chunk, at H2 or deeper. OpenCrane skips the page title (H1). The anchor is a slug: the URL fragment that the documentation site generates from the heading text. source_url holds the page URL without a fragment. MCP clients and AI agents build a direct link to the section by joining the two values:

{source_url}#{section_anchor}

For example, a chunk under the "Who We Serve" heading of the About page gets source_url: https://docs.example.com/guide/about and section_anchor: who-we-serve. The direct link is https://docs.example.com/guide/about#who-we-serve. The search_docs results show the anchor on a Section Anchor: line, and get_metadata_schema documents it.

Choose an anchor style

To choose the slug style, set section_anchor_style in .opencrane/config.yaml. You don't need a config subclass for this setting. The setting accepts the following values:

• generic: builds GitBook-style and GitHub-style slugs. This is the default.
• none: turns section anchors off.

Any other value also turns section anchors off. The following example sets the default style:

section_anchor_style: generic   # default: GitBook/GitHub-style slugs
# section_anchor_style: none    # disable section anchors entirely

Write a custom anchor builder

If your documentation host builds heading slugs in a different way, override section_anchor_for in your config subclass, for example the Config class in .opencrane/extensions.py. Your override receives the nearest heading. It must return the fragment slug without the #, or None to skip the anchor. The following example shows an override:

from opencrane import OpenCraneConfig


class Config(OpenCraneConfig):
    def section_anchor_for(self, heading):
        if not heading:
            return None
        # Example: a host that lowercases and uses underscores instead of hyphens
        return heading.strip().lower().replace(" ", "_")

An override takes precedence over section_anchor_style.

Section navigation and clause IDs

Each prose chunk records its heading path and clause number. The get_section tool uses them to return whole sections. For the fields, see Prose navigation metadata.

To change the clause format, set section_clause_pattern in .opencrane/config.yaml to a regular expression whose first capture group is the clause ID. The value none turns clause IDs off. The following example matches plain dotted numbers:

section_clause_pattern: '(\d+(?:\.\d+)*)\s'

To turn the navigation metadata off, set prose_navigation = False in your config subclass.

An index from an earlier OpenCrane version has no navigation metadata, so the server does not offer get_section. To add the metadata, run opencrane chunk and opencrane embed, and then run opencrane index.

The following command rebuilds the index:

opencrane chunk && opencrane embed && opencrane index

Built-in fence types

A fence type is the language identifier after the opening backticks of a code block, for example openapi in ```openapi. OpenCraneConfig registers the following fence types by default:

• openapi
• asyncapi
• crd
• json-schema

Each type uses the opencrane.fences.inline_file handler. The handler reads the file path written inside the fence block and replaces the block with the file content. The path is relative to the Markdown file, and the file must be inside the project. If the file is missing or outside the project, the handler writes a # Source missing comment instead. When OpenCrane can build the source URL of the file, the handler adds the URL as a ### {source_url} heading. The chunks from the file then get that URL.

The following Markdown example uses two of the built-in fence types:

```openapi
path/to/openapi.json
```

```asyncapi
path/to/asyncapi.yaml
```

You don't need a config subclass to use these types. To keep these built-in types when you add your own, include **OpenCraneConfig.fence_types when you define fence_types in your config subclass. The example in Extend OpenCrane shows how.

Built-in YAML tree walkers

A YAML tree walker splits one kind of structured YAML document into chunks that follow the structure of the document. OpenCrane includes the following YAML tree walkers:

• K8sCRDTreeWalker: Kubernetes CustomResourceDefinitions
• OpenAPITreeWalker: OpenAPI 3.x specs
• JsonSchemaTreeWalker: JSON Schema documents

Write a custom fence type

To add a fence type, register a fence language identifier and provide a handler function. The fence language identifier is the word after the opening backticks of a fence block. When the llms step finds a fence block of that type, OpenCrane calls your handler with the raw block content and the file context. OpenCrane then replaces the block with the string that the handler returns. The following example registers a handler for the my-type fence type:

from pathlib import Path
from opencrane import OpenCraneConfig
from opencrane.fences import CodeFenceConfig

def my_handler(content: str, file_path: Path, project_dir: Path, project_name: str) -> str:
    # content:      raw text inside the fence block
    # file_path:    path of the Markdown file that contains the block
    # project_dir:  root directory of the project being processed
    # project_name: name of the project, used to build source URLs
    # return the full replacement string
    return f"```yaml\n# processed\n{content}\n```\n"

class Config(OpenCraneConfig):
    fence_types = {
        **OpenCraneConfig.fence_types,
        "my-type": CodeFenceConfig(fence_type="my-type", handler=my_handler),
    }

To inline a file that the block references by path, pass handler=inline_file from opencrane.fences, as the terraform entry in the example in Extend OpenCrane does. The handler works as described in Built-in fence types.

Write a custom YAML tree walker

To support a custom YAML document format, subclass YamlTreeWalker, as in the following example:

from opencrane.walkers import YamlTreeWalker

class TerraformTreeWalker(YamlTreeWalker):
    @classmethod
    def can_handle(cls, doc: dict) -> bool:
        return "terraform" in doc

    def walk(self):
        # return List[Chunk]
        ...

The can_handle method returns True for the documents that the walker supports. The walk method returns the chunks of the document. Each chunk needs a chunk_type. The walker can use a built-in chunk type or its own custom chunk type, such as terraform_resource. For the naming rules, see Custom chunk types.

To register the walker, add it to yaml_tree_walkers, as in the example in Extend OpenCrane.

Add custom MCP tools

To serve custom MCP tools on both transports, list ExtraTool entries in extra_tools. Your agents then get project-specific lookups without a second MCP server.

The following example adds a tool that returns the stored content of a chunk:

from opencrane import ExtraTool, OpenCraneConfig


def read_chunk(arguments, context):
    chunk = context.milvus.get_chunk(arguments["chunk_id"])
    allowed = context.allowed_sources()
    if chunk is None or (allowed is not None and chunk["source_name"] not in allowed):
        raise ValueError(f"Chunk not found: {arguments['chunk_id']}")
    return {"source": chunk["source_file"], "content": chunk["content"]}


class Config(OpenCraneConfig):
    extra_tools = [
        ExtraTool(
            name="read_chunk",
            description="Returns the full stored content of a chunk by its ID.",
            input_schema={
                "type": "object",
                "properties": {"chunk_id": {"type": "string"}},
                "required": ["chunk_id"],
            },
            handler=read_chunk,
        ),
    ]

OpenCrane calls the synchronous or asynchronous handler as handler(arguments, context). If name matches another extra tool or a built-in tool other than get_section, the server does not start.

The context argument is a ToolContext with the following members:

OpenCrane sends the handler's return value to the client as follows:

• A string becomes a text content block.
• An MCP content block, or a list of them, stays unchanged.
• Any other value becomes JSON text.

If the handler raises an exception, the client receives an MCP tool error with the exception message.

Authentication and authorization

The HTTP transport (opencrane serve --transport http) supports OAuth 2.1 authentication and scope-based authorization of content. The stdio transport has no authentication, following the MCP specification.

You choose the authentication mode with the auth.type key in .opencrane/config.yaml. The default mode, none, has no authentication. The other modes need the PUBLIC_URL environment variable, set to the public base URL of the server. The exception is oauth with allow_anonymous: true. The following table lists the modes with authentication:

To limit which sources a caller can search, set scope_sources. It maps OAuth scopes to sets of documentation sources. Callers get content only from the sources that the scopes of their token allow.

For authorization that the configuration cannot express, register a custom ASGI middleware on your OpenCraneConfig subclass. Your middleware can call set_allowed_sources(...) from opencrane.mcp.auth.runtime to declare the sources that a request may access. For example, the middleware can get the allowed sources from an external permissions service.

The authentication and authorization guide has the full configuration reference, including the environment variables and a complete middleware example.

Development

The following commands clone the repository and install the development dependencies with pip or with uv:

git clone https://github.com/derberg/OpenCrane.git
cd OpenCrane

# with pip
pip install -e ".[dev]"

# with uv
uv sync --extra dev

To run the tests, use the following command:

./pytest.sh

For more test options, see Run the tests. For the development setup, see Development.

Credits

OpenCrane started from a real-world use case at Cennso: AI-powered search over telecommunications product documentation.

OpenCrane builds on the following open-source projects:

• Milvus: vector database that runs the similarity search
• Docling: document parsing and chunking
• sentence-transformers: embedding generation
• rank-bm25: keyword search with the BM25 ranking function, which complements vector similarity search
• Model Context Protocol: the protocol that lets AI clients call the search tools

License

OpenCrane uses the Apache License 2.0. For the full text, see LICENSE.