Feat: Add MCP Server Interface for Repository Intelligence

[marco0560]

Feat: Add MCP Server Interface for Repository Intelligence

Summary

Expose Codira as a Model Context Protocol (MCP) server, allowing AI agents and MCP-capable clients to consume Codira's repository intelligence through a stable, structured tool interface.

The goal is not to expose arbitrary filesystem access. The goal is to expose Codira's semantic repository model.

Examples of target clients:

• Codex CLI / Codex TUI
• Claude Desktop
• Claude Code
• Goose
• Cursor
• Other MCP-compatible tools

Motivation

Codira already provides repository intelligence that is substantially richer than generic repository-access tools:

• exact symbol lookup
• symbol inventory
• call graph navigation
• reference navigation
• semantic repository context
• documentation retrieval
• coverage auditing
• capability-contract export

Today these capabilities are exposed through the CLI.

An MCP interface would allow AI agents to consume the same information directly without shelling out to Codira-specific commands.

Non-goals

This issue does not aim to:

• expose arbitrary filesystem access
• expose arbitrary shell execution
• replace the CLI
• introduce remote networking requirements
• introduce authentication or authorization systems
• expose write operations

Initial scope is local, read-only repository intelligence.

Proposed Architecture

Phase 0: MCP Contract Design

Define:

• tool inventory
• request schemas
• response schemas
• error semantics
• repository-selection model
• capability-discovery model

The capability contract should remain the source of truth for discoverability.

Phase 1: Local Read-Only MCP Server

Implement a local MCP server exposing a minimal set of tools.

Candidate tools:

MCP Tool	Backing Command
caps	codira caps
sym	codira sym
symlist	codira symlist
refs	codira refs
calls	codira calls
ctx	codira ctx
audit	codira audit
cov	codira cov

The server should use Codira APIs directly rather than invoking subprocesses.

Phase 2: Repository Management

Support:

• multiple repositories
• repository identifiers
• repository metadata
• repository status reporting

Avoid exposing arbitrary filesystem paths through MCP requests.

Phase 3: Advanced Semantic Tools

Evaluate exposing:

• docs
• emb
• index-health information
• embedding inventory information
• deferred-embedding status

Phase 4: Daemon Integration

If daemon mode is implemented:

• reuse warm indexes
• avoid repeated process startup
• support shared multi-repository databases

Design Principles

Semantic-first

The MCP interface should expose Codira's semantic model rather than raw repository contents.

Read-only by default

Initial MCP tools should not mutate repositories.

Deterministic output

Tool responses should remain deterministic and machine-consumable.

Capability discovery

Clients should be able to discover available capabilities through a capability-contract surface.

Backend neutrality

The MCP layer must operate consistently across:

• SQLite backend
• DuckDB backend
• memory backend

Open Questions

Repository selection

Should tools accept:

repo_id

or

repository_name

or both?

Capability exposure

Should MCP tools map directly to CLI commands, or should the MCP interface define a higher-level semantic API?

Result size limits

How should large outputs such as:

• symlist
• large call graphs
• large context retrievals

be paginated or truncated?

Daemon dependency

Should the MCP server:

• operate standalone
• optionally use daemon mode
• require daemon mode

Acceptance Criteria

• Architecture documented.
• MCP tool inventory defined.
• Request/response schemas defined.
• Repository-selection model defined.
• Error model defined.
• Follow-up implementation issues identified.
• No commitment to a specific transport or daemon architecture before design review.

Suggested Labels

enhancement
architecture
mcp
agent-integration
discussion