ossctx 0.1.0b2

Unified Python CLI for code, docs, and otel context tooling

ossctx

ossctx is a unified Python toolkit for building local context services around source code, documentation, and telemetry.

It brings three related systems under one CLI and one package:

• ossCtx code for source indexing, dependency analysis, call-graph queries, API serving, and MCP access
• ossCtx docs for document indexing, website crawling, search, analysis, API serving, and MCP access
• ossCtx otel for trace/log/metric ingestion, observability APIs, OTLP compatibility, and MCP access

The goal is to provide a consistent local operator workflow for indexing information, exposing it through HTTP and MCP, and integrating it into editor and agent tooling.

Project structure

The package is organized into four top-level Python packages:

• common contains shared CLI, config, database, middleware, and server helpers
• codectx implements code indexing and graph queries
• docsctx implements document ingestion, crawling, analysis, and retrieval
• otelctx implements telemetry ingestion, storage, search, and service graph features

Features

Code context

• Index local source trees into SQLite
• Extract entities, dependencies, and relations
• Query entities, file dependencies, and call graphs
• Run an HTTP API server for indexed code data
• Run or configure an MCP server for editor and agent integrations
• Install compatibility alias: codecontext

Document context

• Index local text, markdown, and HTML content
• Crawl documentation sites from a root URL
• Chunk and persist document content
• Run deterministic or provider-backed finalize analysis
• Search indexed content and inspect communities/entities through HTTP APIs
• Run or configure an MCP server for document search workflows
• Install compatibility alias: docscontext

Telemetry context

• Ingest traces, logs, and metrics from JSON payloads
• Support OTLP HTTP JSON compatibility routes
• Support OTLP gRPC ingestion when dependencies are available
• Query traces, logs, metrics, services, archive, DLQ, TSDB, and health data via HTTP APIs
• Expose websocket and optional Prometheus integrations
• Run or configure an MCP server for observability workflows
• Install compatibility alias: otelcontext

Requirements

• Python >=3.11
• Windows, macOS, or Linux with a working Python environment

Installation

Install from the repo root using uv:

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

Install with development extras:

uv pip install -e ".[dev]"

Install with optional parser and loader support:

uv pip install -e ".[dev,tree-sitter,loaders]"

Running

You can use uv run to execute the CLI commands without explicitly activating the virtual environment:

# Run the main CLI
uv run ossCtx --help

# Serve the UI
uv run ossCtx ui serve

# Run specific contexts
uv run ossCtx code --help
uv run ossCtx docs --help
uv run ossCtx otel --help

Optional extras:

• dev adds pytest, ruff, mypy, and pip-audit
• tree-sitter adds higher-fidelity parsers for supported languages
• loaders adds PDF and Word document ingestion support

Installed commands

Primary entrypoint:

• ossCtx

Compatibility aliases:

• codecontext
• docscontext
• otelcontext

Version command:

ossCtx --version

Quickstart

Index code

ossCtx code index . --db .codecontext.db
ossCtx code stats --db .codecontext.db
ossCtx code query entity hello --db .codecontext.db

Index documents

ossCtx docs index ./docs --db .docscontext.db --finalize
ossCtx docs stats --db .docscontext.db
ossCtx docs serve --db .docscontext.db --port 8090

Crawl a documentation website

ossCtx docs index --url https://example.com/docs --db .docscontext.db --max-pages 100 --max-depth 2 --finalize

Ingest telemetry

ossCtx otel ingest traces.json --db .otelcontext.db
ossCtx otel stats --db .otelcontext.db
ossCtx otel serve --db .otelcontext.db --http-port 8088 --grpc-port 4317

Default storage and ports

Default SQLite files:

• Code: .codecontext.db
• Docs: .docscontext.db
• Otel: .otelcontext.db

Default API ports:

• Code: 8080
• Docs: 8090
• Otel HTTP: 8088
• Otel gRPC: 4317

Default Otel archive directory:

• .otel_archive

Command reference

Root CLI

ossCtx --version
ossCtx code ...
ossCtx docs ...
ossCtx otel ...

Code commands

ossCtx code index

Index a directory into the code database.

ossCtx code index <path> [--db PATH] [--max-file-size MB]

Important options:

• --db overrides the SQLite path
• --max-file-size skips very large files during indexing

ossCtx code query

Query indexed code data.

ossCtx code query entity <name> [--db PATH]
ossCtx code query deps <file-path> [--db PATH]
ossCtx code query calls <entity-name> [--db PATH]

Query types:

• entity finds matching entities by name
• deps prints file dependency information
• calls prints outgoing and incoming call edges

ossCtx code stats

Show code index statistics.

ossCtx code stats [--db PATH]

ossCtx code clean

Delete the code database and SQLite sidecar files.

ossCtx code clean [--db PATH]

ossCtx code serve

Run the code HTTP API server.

ossCtx code serve [--host HOST] [--port PORT] [--db PATH]

ossCtx code mcp

Run the CodeCtx MCP server.

ossCtx code mcp [--transport stdio|sse|streamable-http] [--addr HOST:PORT] [--db PATH]

Examples:

ossCtx code mcp --transport stdio --db .codecontext.db
ossCtx code mcp --transport streamable-http --addr 127.0.0.1:8081 --db .codecontext.db
ossCtx code mcp --transport sse --addr 127.0.0.1:8081 --db .codecontext.db

ossCtx code setup

Write or update a VS Code MCP config entry for CodeCtx.

ossCtx code setup [--binary BIN] [--transport TYPE] [--addr HOST:PORT] [--db PATH] [--output PATH] [--server-name NAME]

Example:

ossCtx code setup --output .vscode/mcp.json --db .codecontext.db

Docs commands

ossCtx docs index

Index local files or crawl a documentation site.

ossCtx docs index <path> [--db PATH] [--chunk-size N] [--chunk-overlap N] [--finalize]
ossCtx docs index --url URL [--db PATH] [--max-pages N] [--max-depth N] [--allow-external] [--same-path-prefix|--no-same-path-prefix] [--timeout SECONDS] [--finalize]

Important options:

• --url crawls from a root site instead of indexing a local path
• --chunk-size and --chunk-overlap tune chunking behavior
• --max-pages and --max-depth control crawl size
• --allow-external allows following links outside the root host
• --same-path-prefix restricts crawling to the original path prefix
• --finalize runs structure/entity/community analysis after ingest

ossCtx docs stats

Show document index statistics.

ossCtx docs stats [--db PATH] [--json]

ossCtx docs serve

Run the DocsCtx HTTP API server.

ossCtx docs serve [--host HOST] [--port PORT] [--db PATH]

ossCtx docs mcp

Run the DocsCtx MCP server.

ossCtx docs mcp [--transport stdio|sse|streamable-http] [--db PATH]

ossCtx docs setup

Write or update a VS Code MCP config for DocsCtx.

ossCtx docs setup [--output PATH] [--transport TYPE]

Otel commands

ossCtx otel ingest

Ingest a JSON payload file containing traces, logs, metrics, or OTLP-compatible payloads.

ossCtx otel ingest <path> [--db PATH]

ossCtx otel stats

Show telemetry statistics.

ossCtx otel stats [--db PATH]

ossCtx otel serve

Run the OtelCtx HTTP API server and optional OTLP gRPC receiver.

ossCtx otel serve [--host HOST] [--http-port PORT] [--grpc-port PORT] [--db PATH]

Notes:

• HTTP API defaults to port 8088
• OTLP gRPC defaults to port 4317
• If gRPC dependencies are unavailable, the HTTP server can still run

ossCtx otel mcp

Run the OtelCtx MCP server.

ossCtx otel mcp [--transport stdio|sse|streamable-http] [--addr HOST:PORT] [--db PATH]

ossCtx otel setup

Write or update a VS Code MCP config entry for OtelCtx.

ossCtx otel setup [--binary BIN] [--transport TYPE] [--addr HOST:PORT] [--db PATH] [--output PATH] [--server-name NAME]

MCP workflows

Each subsystem can run as an MCP server or generate a VS Code MCP config file.

Common patterns:

ossCtx code mcp --transport stdio
ossCtx docs mcp --transport stdio
ossCtx otel mcp --transport stdio

Generate .vscode/mcp.json entries:

ossCtx code setup --output .vscode/mcp.json
ossCtx docs setup --output .vscode/mcp.json
ossCtx otel setup --output .vscode/mcp.json

Transport modes:

• stdio for local process-based MCP integration
• sse for HTTP SSE transport where supported
• streamable-http for HTTP MCP endpoints where supported

Supported content and formats

Code parsing

The parser registry supports a broad set of source and config formats, including:

• Python
• Go
• JavaScript and TypeScript
• Java
• Rust
• C#
• Ruby
• SQL
• Kotlin
• Scala
• Bash
• Lua
• Perl
• R
• HTML
• CSS
• Markdown
• JSON
• XML
• YAML
• TOML
• HCL
• Properties
• Dockerfile

Installing the tree-sitter extra improves fidelity for supported languages.

Document formats

Built-in local document loading supports:

• .txt
• .text
• .md
• .markdown
• .html
• .htm

Optional loader extras add:

• PDF via pymupdf
• Word documents via python-docx

API overview

Code API

Run it with:

ossCtx code serve --db .codecontext.db

It exposes shared health/version endpoints plus codectx routes for stats, file/entity lookup, dependency graphs, and call-graph access.

Docs API

Run it with:

ossCtx docs serve --db .docscontext.db

It exposes shared health/version endpoints plus document listing, retrieval, versions, upload, search, finalize, upload progress, communities, entities, and graph neighborhood routes.

Otel API

Run it with:

ossCtx otel serve --db .otelcontext.db

It exposes shared health/version endpoints plus traces, logs, metrics, services, dashboard, archive, DLQ, sampler, graph, ingest, OTLP compatibility, and websocket routes.

Configuration

The package uses environment-driven settings via Pydantic settings models.

Useful environment variables include:

CodeCtx

• CODECTX_DB_PATH
• CODECTX_HOST
• CODECTX_PORT
• CODECTX_MAX_FILE_SIZE_MB

DocsCtx

• DOCSCTX_DB_PATH
• DOCSCTX_HOST
• DOCSCTX_PORT
• DOCSCTX_CHUNK_SIZE
• DOCSCTX_CHUNK_OVERLAP
• DOCSCTX_MAX_PAGES
• DOCSCTX_MAX_DEPTH
• DOCSCTX_LLM_PROVIDER
• DOCSCTX_LLM_MODEL
• DOCSCTX_LLM_BASE_URL
• DOCSCTX_LLM_API_KEY
• DOCSCTX_LLM_TIMEOUT_SECONDS
• DOCSCTX_LLM_MAX_RETRIES
• DOCSCTX_LLM_RETRY_BACKOFF_SECONDS
• DOCSCTX_LLM_FALLBACK_ON_ERROR
• DOCSCTX_EMBED_MODEL
• DOCSCTX_EMBED_BASE_URL
• DOCSCTX_EMBED_API_KEY
• DOCSCTX_EMBED_BATCH_SIZE

OtelCtx

• OTELCTX_DB_PATH
• OTELCTX_HOST
• OTELCTX_PORT
• OTELCTX_GRPC_PORT
• OTELCTX_ARCHIVE_DIR
• OTELCTX_HOT_DAYS
• OTELCTX_TSDB_CAPACITY
• OTELCTX_SAMPLING_RATE
• OTELCTX_SAMPLING_ALWAYS_ERRORS
• OTELCTX_SAMPLING_LATENCY_THRESHOLD_MS
• OTELCTX_DLQ_MAX_RETRIES
• OTELCTX_DLQ_REPLAY_INTERVAL_SECONDS
• OTELCTX_WS_BUFFER_SIZE
• OTELCTX_WS_FLUSH_INTERVAL_MS
• OTELCTX_PROMETHEUS_ENABLED

Development

Run tests:

python -m pytest -q

Verified test command in the current environment:

d:/Development/omni-agents/.venv/Scripts/python.exe -m pytest -q

Useful development tasks:

python -m pip install -e .[dev,tree-sitter,loaders]
python -m pytest -q
ruff check .
mypy .

Publishing notes

The package metadata declares:

• project name: ossctx
• version: 0.1.0
• license: MIT
• console scripts: ossCtx, codecontext, docscontext, otelcontext

License

This project is licensed under the MIT License. See LICENSE.