yvgude--lean-ctx/docs/contracts/provider-framework-contract-v1.md

Provider Framework Contract v1

Status: Stable
Version: PROVIDER_FRAMEWORK_V1_SCHEMA_VERSION = 1
Runtime source: rust/src/core/providers/

Purpose

Provides structured access to external context sources through the MCP tool interface. All provider data is a first-class citizen: it flows through the full consolidation pipeline into BM25 index, Graph index, Knowledge facts, and Session cache.

Architecture

ContextProvider::execute()
    → ProviderResult
    → consolidation::consolidate()
    → ConsolidationArtifacts { bm25_chunks, edges, facts, cache_entries }
    → apply_artifacts_to_stores() [background thread]
        → BM25Index::ingest()       — searchable via ctx_semantic_search
        → GraphIndex::merge_edges() — cross-source hints in ctx_read
        → Knowledge::remember()     — recallable via ctx_knowledge
        → SessionCache::set()       — fast re-reads

Built-in Providers

Provider	Auto-activates when	Resources
GitHub	GITHUB_TOKEN set	issues, pull_requests, actions
GitLab	GITLAB_TOKEN set	issues, merge_requests, pipelines
Jira	JIRA_TOKEN set	issues, sprints, projects
PostgreSQL	DATABASE_URL set	tables, schemas, queries

Config-based Providers

Custom REST APIs via TOML/JSON in ~/.config/lean-ctx/providers/ or .lean-ctx/providers/. Supports 6 auth methods (bearer, API key, basic, header, query param, none).

MCP Bridge Providers

External MCP servers connected via [providers.mcp_bridges.<name>] config. Each bridge registers with unique ID mcp:<name>. Supports:

• HTTP transport (url = "http://...")
• Stdio transport (command = "npx", args = ["-y", "@mcp/server"])
• Actions: resources (list), read_resource (fetch single), tools (list)

ctx_provider Actions

Action	Parameters	Description
gitlab_issues	state, labels, limit	List issues (sorted by updated_at desc)
gitlab_issue	iid	Show single issue with description
gitlab_mrs	state, limit	List merge requests
gitlab_pipelines	status, limit	List pipelines
mcp_resources	—	List all resources from configured MCP bridges

Configuration

Token resolution order:

1. LEAN_CTX_GITLAB_TOKEN
2. GITLAB_TOKEN
3. CI_JOB_TOKEN

Host resolution:

1. GITLAB_HOST
2. CI_SERVER_HOST
3. Default: gitlab.com

Project path resolution:

1. CI_PROJECT_PATH
2. Auto-detect from git remote get-url origin

ProviderResult Schema

struct ProviderResult {
    provider: String,       // "gitlab"
    resource_type: String,  // "issues", "merge_requests", "pipelines"
    items: Vec<ProviderItem>,
    total_count: Option<usize>,
    truncated: bool,
}

struct ProviderItem {
    id: String,
    title: String,
    state: Option<String>,
    author: Option<String>,
    created_at: Option<String>,
    updated_at: Option<String>,
    url: Option<String>,
    labels: Vec<String>,
    body: Option<String>,
}

Caching & Indexing

• Session cache: TTL-based in-memory cache (120 seconds default). Cache key includes provider, resource type, project, filters
• BM25 index: External chunks indexed with ChunkKind metadata (Issue, PullRequest, DbSchema, etc.)
• Graph index: Cross-source edges link external URIs to code files (e.g. issue → src/auth.rs)
• Knowledge facts: Extracted categories: known_bugs, known_features, recent_changes, data_model, documentation, file_mentions
• providers.auto_index: Controls background indexing (default: true)

Security

• All provider outputs pass through redact_text_if_enabled
• CI job logs pass through secret scanner before delivery
• Tokens never appear in tool output
• MCP bridges: optional auth_env field for token injection from env vars

Shell Compression (glab / gh CLI)

Patterns for CLI output:

• glab/gh issue list/view, MR/PR list/view, CI/actions status
• Compression follows pattern-based structure

Context IR Integration

Provider outputs are tracked as ContextIrSourceKindV1::Provider in the evidence ledger, enabling:

• Provenance tracking (which provider data informed a decision)
• Replay verification
• Token attribution

Diagnostics

lean-ctx doctor validates:

• Provider env vars (GITHUB_TOKEN, GITLAB_TOKEN, etc.)
• MCP bridge URLs (reachable, configured)
• auto_index status (warns if false)