Skip to main content
Glama

openground

PyPI version

tldr: openground lets you give controlled access to documentation to AI agents. Everything happens on-device.

openground is an on-device RAG system that extracts documentation from git repos and sitemaps, embeds it for semantic search, and exposes it to AI agents via MCP. It uses a local embedding model, and local lancedb for storing embeddings and for hybrid vector similarity and BM25 full-text search.

Architecture

      ┌─────────────────────────────────────────────────────────────────────┐
      │                           OPENGROUND                                │
      ├─────────────────────────────────────────────────────────────────────┤
      │                                                                     │
      │       SOURCE                  PROCESS              STORAGE/CLIENT   │
      │                                                                     │
      │    ┌──────────┐      ┌───────────┐   ┌──────────┐   ┌──────────┐    │
      │    │ git repo ├─────>│  Extract  ├──>│  Chunk   ├──>│ LanceDB  │    │
      │    |   -or-   |      │ (raw_data)│   │   Text   │   │ (vector  │    │
      │    │ sitemap  │      └───────────┘   └──────────┘   │  +BM25)  │    │
      │    │   -or-   │                           │         └────┬─────┘    │
      │    │ local dir│                           │              │          │
      │    └──────────┘                           │              │          │
      │                                           ▼              │          │
      │                                    ┌───────────┐         │          │
      │                                    │   Local   |<────────┘          │
      │                                    │ Embedding │         │          │
      │                                    │   Model   │         ▼          │
      │                                    └───────────┘  ┌─────────────┐   │
      │                                                   │ CLI / MCP   │   │
      │                                                   │  (hybrid    │   │
      |                                                   |   search)   |   |
      │                                                   └─────────────┘   │
      │                                                                     │
      └─────────────────────────────────────────────────────────────────────┘

Related MCP server: tech-doc-mcp

Quick Start

Installation

Recommended to install with uv:

uv tool install openground # Larger package size, automatic GPU/MPS/CPU support
uv tool install 'openground[fastembed]' # Lightweight CPU support
uv tool install 'openground[fastembed-gpu]' # Experimental CUDA/GPU support through fastembed

or

pip install openground

Add Documentation

Openground can source documentation from git repos, sitemaps, or local directories.

To add documentation from a git repo to openground, run:

openground add library-name \
  --source https://github.com/example/example.git \
  --docs-path docs/ \
  --version v1.0.0 \ # gets v1.0.0 docs using git tags
  -y

The --version flag specifies a git tag to checkout (defaults to latest).

To add documentation from a sitemap to openground:

openground add library-name \
  --source https://docs.example.com/sitemap.xml \
  --filter-keyword docs \ 
  --filter-keyword blog \
  -y

To add documentation from a local path to openground:

# Absolute path
openground add library-name --source /path/to/docs -y

# Home directory
openground add library-name --source ~/path/to/docs -y

# Relative path (from current directory)
openground add library-name --source ./docs -y
openground add library-name --source ../docs -y
openground add library-name --source docs -y

Git and local directory additions support .md, .rst, .txt, .mdx, .ipynb, .html, and .htm files.

This will download the docs, embed them, and store them into lancedb. All locally.

Multiple versions of the same library can be stored and queried independently.

Sources Files

Openground uses sources.json files to store library source configurations. When you add documentation with --source, openground remembers the source URL so you can add/update the same library later by just specifying its name.

How Sources Files Work

There are two types of sources files:

  1. User Sources File (~/.openground/sources.json)

    • Shared across all your projects

    • Created automatically when you first use --source flag

    • This is where new sources are saved by default

  2. Project Sources File (.openground/sources.json)

    • Project-specific overrides

    • Created automatically in each project when you add a source

    • Takes priority over user sources when both exist

Priority Order

When looking up a library by name, openground checks:

  1. Custom path via --sources-file flag

  2. Project-local .openground/sources.json (if exists)

  3. User ~/.openground/sources.json (if exists)

  4. Package-level bundled sources

Example Workflow

# In project1: Add library with source
cd project1/
openground add fastapi --source https://github.com/tiangolo/fastapi.git --docs-path docs/

# In project2: Same library is now available by name!
cd ../project2/
openground add fastapi  # Finds source from ~/.openground/sources.json

# Project-specific override: Add a different version for this project
echo '{"fastapi": {"type": "git_repo", "repo_url": "https://github.com/tiangolo/fastapi.git", "docs_paths": ["docs"], "languages": ["python"]}}' > .openground/sources.json

Managing Sources

Sources are stored as JSON with this structure:

{
  "fastapi": {
    "type": "git_repo",
    "repo_url": "https://github.com/tiangolo/fastapi",
    "docs_paths": ["docs"],
  },
  "numpy": {
    "type": "sitemap",
    "sitemap_url": "https://numpy.org/doc/sitemap.xml",
    "filter_keywords": ["docs/"]
  }
}

To disable automatic source saving:

openground config set sources.auto_add_local false

Use with AI Agents

To install the MCP server:

# For Cursor
openground install-mcp --cursor

# For Claude Code
openground install-mcp --claude-code

# For OpenCode
openground install-mcp --opencode

# For any other agent
openground install-mcp

Now your AI assistant can search your stored documentation automatically!

Example Workflow

Here's how to add the fastembed documentation and make it available to Claude Code:

# 1. Install openground
uv tool install openground

# 2. Add fastembed to openground
openground add fastembed --source https://github.com/qdrant/fastembed.git --docs-path docs/ --version v0.7.4 -y

# 3. Configure Claude Code to use openground MCP
openground install-mcp --claude-code

# 4. Restart Claude Code
# Now you can ask: "What models are available in fastembed?"
# Claude will search the fastembed docs automatically!

Claude Code Agent

Openground includes a custom Claude Code agent that searches official documentation without polluting your main conversation context. See docs/claude-code-agent.md for installation and usage instructions.

MCP Usage Statistics

To see how many times each tool in the MCP server has been called:

openground stats show # show stats
openground stats clear # reset stats

Development

To contribute or work on openground locally:

git clone https://github.com/poweroutlet2/openground.git
cd openground
uv sync .

License

MIT

Available Tools

3 tools
get_full_content_toolA

Retrieve the full content of a document by its URL and version.

Use this tool when you need to see the complete content of a page that was returned in search results. The URL and version are provided in the search result's tool hint.

Inputs: url (required), version (required). Returns: result

list_libraries_toolA

Retrieve a dictionary of available documentation libraries/frameworks with their versions.

Returns a dictionary mapping library names to lists of available versions. Use this tool to see what documentation is available before performing a search. If the desired library is not in the list, you may prompt the user to add it.

Args: search_term: Optional search term to filter library names (case-insensitive). If provided, only libraries whose names contain the search term will be returned.

Inputs: no named parameters. Returns: object

search_documents_toolA

Search the official documentation knowledge base to answer user questions.

Always used this tool when a question might be answered or confirmed from the documentation.

First call list_libraries_tool to see what libraries and versions are available, then filter by library_name and version.

Inputs: query (required), version (required), library_name (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool serves a distinct, non-overlapping role: listing available documentation, searching within it, and retrieving full content. There is no ambiguity about which tool to use for a given step in the workflow.

    Naming Consistency5/5

    All tools follow a consistent snake_case verb_noun_tool naming pattern (search_documents_tool, list_libraries_tool, get_full_content_tool). This is highly predictable and aids agent selection.

    Tool Count5/5

    With only 3 tools, the server is tightly scoped to its documentation-searching purpose. Each tool is essential and the count is well within the ideal range for a focused server.

    Completeness5/5

    The tool set covers the full lifecycle of documentation interaction: discover available libraries, search for relevant documents, and fetch full content when needed. No obvious gaps or dead ends exist for the intended use case.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides up-to-date documentation for AI agents by locally querying a community-driven registry of pre-built docs packages.
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables agents to retrieve relevant context from local documents via MCP tools, supporting ingestion, semantic search, metadata filtering, and evidence inspection entirely on-device.
      MIT