Installation

Contextia can be installed as a standalone CLI tool, as a Python package, or run directly with uvx without permanent installation. This guide covers all methods and shows how to configure the MCP server for your editor.

Prerequisites

• Python 3.12 or later — Contextia uses modern Python features including type parameter syntax and typing improvements introduced in 3.12
• uv (recommended) — a fast Python package manager. Install it from docs.astral.sh/uv

Tip

If you do not have uv installed, you can get it with a single command:

curl -LsSf https://astral.sh/uv/install.sh | sh

On macOS, you can also use Homebrew:

brew install uv

Installing the CLI

With uv (recommended)

The fastest way to use Contextia is with uvx, which runs the tool directly without installing it into your environment:

uvx contextia --version

This downloads Contextia on first run and caches it. No virtual environment management needed.

To install it permanently so the contextia command is always available:

uv tool install contextia

With pip

If you prefer traditional pip installation:

pip install contextia

Caution

When installing with pip, make sure you are using Python 3.12 or later. You can verify with python --version. Consider using a virtual environment to avoid conflicts with other packages.

With language grammar support

Contextia can parse code annotations (@spec, @decision, etc.) using regex by default. For more accurate parsing with tree-sitter grammars, install with the languages extra:

pip install contextia[languages]

Or with uv:

uv tool install contextia[languages]

This installs tree-sitter grammars for Python, TypeScript, JavaScript, Go, Rust, and Java. Tree-sitter provides AST-level parsing, which means Contextia can reliably detect the function or class containing an annotation, not just the line it appears on.

Note

Language grammar support is optional. The regex-based scanner works well for most projects. You only need tree-sitter if you want richer context from annotation scanning (e.g., knowing that @spec SPEC-001 appears inside class PaymentProcessor.process_payment()).

Verifying the installation

After installing, verify that Contextia is available:

contextia --version

You should see output like:

contextia 0.1.0

You can also check that the CLI is working by running the help command:

contextia --help

This displays all available commands with brief descriptions.

Setting up the MCP server

The MCP server (contextia-mcp) allows AI agents to access your project’s context architecture directly through the Model Context Protocol. The server runs as a local stdio process — no HTTP, no authentication, no external network access.

The server automatically discovers your project by walking up from the working directory looking for .contextia/config.yaml, just like git discovers .git/. No per-project configuration is needed in your editor.

Claude Code

Register the MCP server with Claude Code using a single command:

claude mcp add contextia -- uvx contextia-mcp

This tells Claude Code to start the Contextia MCP server when needed. The server inherits the working directory from Claude Code, so it automatically finds your project root.

To verify the server is registered:

claude mcp list

You should see contextia in the list of configured servers.

Cursor

Create or edit .cursor/mcp.json in your project root:

.cursor/mcp.json

{
  "mcpServers": {
    "contextia": {
      "command": "uvx",
      "args": ["contextia-mcp"]
    }
  }
}

Restart Cursor after adding this configuration. The MCP server will be available to the AI agent in all files within the project.

VS Code

Create or edit .vscode/mcp.json in your project root:

.vscode/mcp.json

{
  "servers": {
    "contextia": {
      "type": "stdio",
      "command": "uvx",
      "args": ["contextia-mcp"]
    }
  }
}

Note

VS Code MCP support requires the appropriate extension for your AI provider (e.g., the Claude extension or GitHub Copilot with MCP support). Check your extension’s documentation for the exact MCP configuration format, as it may vary.

Verifying the MCP server

You can test the MCP server directly from the command line:

uvx contextia-mcp

The server starts and waits for JSON-RPC messages on stdin. In normal use, your editor manages this process automatically. Press Ctrl+C to stop.

To verify it works with your project, navigate to a directory containing a .contextia/ folder and check that the server starts without errors.

Project-level configuration

Contextia does not require any editor-specific project configuration beyond the MCP server setup above. All project settings live in .contextia/config.yaml, which is created when you run contextia init.

A minimal configuration looks like this:

.contextia/config.yaml

version: "1.0"
project:
  name: my-project
  languages:
    - python
annotations:
  prefix: "@"
  comment_syntax:
    python: "#"

See the Quickstart guide for a walkthrough of initializing your first project.

Upgrading

With uv

uv tool upgrade contextia

With pip

pip install --upgrade contextia

Checking for updates

contextia --version

Compare the output with the latest release on PyPI.

Tip

Contextia follows semantic versioning. Patch releases (0.1.x) contain bug fixes. Minor releases (0.x.0) add features without breaking changes. Major releases (x.0.0) may change the .contextia/ directory format, but will always include a migration command.

Next steps

With Contextia installed and your MCP server configured, head to the Quickstart tutorial to initialize your first project and create your first spec.