Skip to content

CAP release 1.0.1

Choose a tag to compare

View all tags
@domasles domasles released this 08 Feb 18:58
· 7 commits to main since this release
1.0.1
f68ccdf

CAP 1.0.1 Release Notes

Codebase Awareness Protocol - Give AI coding agents the context they need.

Overview

CAP 1.0.1 is the first stable release of the Codebase Awareness Protocol. All packages and APIs are now marked stable and ready for production use.

CAP lets you describe your codebase once in three small YAML files - architecture, dependencies, and API - and serves that knowledge to any AI coding agent through the Model Context Protocol (MCP). The result: agents that understand your layers, respect your dependency rules, and use your public API without you repeating yourself in every prompt.

Packages

Package Version Language Install
cap-core 1.0.1 Python pip install cap-core
cap-mcp 1.0.1 Python pip install cap-mcp
cap-cli 1.0.1 Python pip install cap-cli
cap-vscode 1.0.1 TypeScript VS Code Marketplace

Features

.cap/ Configuration Files

Three declarative YAML files that live in your repository:

  • architecture.yaml - Define your architectural style (e.g. hexagonal), layers with ownership globs and import rules, modules with purpose descriptions, and forbidden call patterns with reasons.
  • dependencies.yaml - Declare runtime and dev dependencies per language with version constraints and reasons, forbidden dependency rules per layer, and free-form notes.
  • api.yaml - Map public and internal exports with file locations, stability markers, and access rules. Define forbidden API usage patterns across paths.

All fields are validated with strict Pydantic schemas. Unknown keys are rejected. Run cap validate to catch mistakes before your agent does.

MCP Server (cap-mcp)

A FastMCP server exposing three tools over stdio transport:

Tool What the agent gets
get_architecture Layers, modules, ownership, import rules, forbidden patterns
get_dependencies Runtime/dev packages, versions, forbidden dependency rules
get_api Public/internal exports, stability, access rules

Any MCP-compatible AI client can connect and call these tools automatically.

CLI (cap-cli)

A Click-based command-line interface:

  • cap init - Scaffold a .cap/ directory with template YAML files. Supports --minimal and --force flags.
  • cap validate - Validate .cap/ files against schemas with rich terminal output. Supports --json for CI pipelines.
  • cap serve - Start the MCP server over stdio for any MCP-compatible client.
  • cap --version - Display the installed version.

VS Code Extension (cap-vscode)

A full-featured extension that handles everything automatically:

  • Automatic Python environment management - Discovers Python ≥3.11, creates an isolated venv, and installs cap-cli.
  • MCP server provider - Registers cap serve as an MCP server per workspace folder using vscode.lm.registerMcpServerDefinitionProvider. AI agents (e.g. GitHub Copilot) discover the tools automatically.
  • Command Palette commands:
    • CAP: Initialize Configuration - Create .cap/ with templates.
    • CAP: Reinitialize Configuration (Overwrite) - Force-recreate .cap/.
    • CAP: Validate Configuration - Validate and report diagnostics.
  • File system watcher - Monitors .cap/ for changes and refreshes the MCP server dynamically.
  • Auto-init prompt - Prompts to create .cap/ when a workspace has no configuration (configurable via cap.autoInit).
  • Auto-update - Checks for cap-cli updates and prompts to upgrade.

Core Library (cap-core)

The foundation layer with hexagonal architecture:

  • Domain models - Pure Pydantic BaseModel subclasses with extra="forbid" for strict validation. Covers ArchitectureYAML, DependenciesYAML, ApiYAML, and validation models (ValidationIssue, ValidationResult, WorkspaceValidation).
  • ConfigService - Main facade for loading and parsing .cap/ YAML files.
  • ValidationService - Validates configuration files with detailed error reporting including line numbers and column positions via YAML composition parsing.
  • MCPFormatter - Transforms domain models into MCP-compatible JSON format.
  • FileReader - Infrastructure layer that handles all filesystem I/O and YAML parsing, including duplicate key detection.

Architecture

CAP follows hexagonal architecture with a strict one-way dependency flow:

cap-cli -> cap-mcp -> cap-core
  • cap-core has zero MCP/CLI dependencies - only PyYAML and Pydantic.
  • cap-mcp depends on cap-core and the MCP SDK.
  • cap-cli depends on cap-mcp (which transitively pulls in cap-core), plus Click and Rich.
  • cap-vscode calls cap-cli as a subprocess - it never imports Python directly.

Requirements

  • Python ≥ 3.11
  • Node.js ≥ 20 (VS Code extension only)
  • VS Code ≥ 1.109.0 (VS Code extension only)
  • Git (for version control integration)

Python Dependencies

Package Version Purpose
pyyaml ≥6.0.3 YAML parsing for .cap/ configuration files
pydantic ≥2.12.5 Domain model validation and serialization
mcp[cli] ≥1.26.0 MCP SDK - FastMCP server, protocol handling, stdio transport
click ≥8.3.1 CLI framework
rich ≥13.3.2 Terminal output formatting

License

Apache License 2.0

Assets 3
Loading