feat: Implement MCP Server Components - Phases 1-3.3 (CFOS-27)

.claude/commands/linear-retroactive-git.md

@@ -202,22 +202,22 @@ Automate the process of converting git working state into comprehensive Linear i
    ## Issues Created (within project):
    - CVIREC-20: Remove duplicate response models from agents
      - Labels: Refactor, Technical Debt
-     - Branch: jay/cvirec-20-remove-duplicate-response-models
+     - Branch: jayscambler/cvirec-20-remove-duplicate-response-models
      - PR: #21
 
    - CVIREC-21: Consolidate tool imports across all agents
      - Labels: Refactor, Improvement
-     - Branch: jay/cvirec-21-consolidate-tool-imports
+     - Branch: jayscambler/cvirec-21-consolidate-tool-imports
      - PR: #22
 
    - CVIREC-22: Update database models and type hints
      - Labels: Improvement, Technical Debt
-     - Branch: jay/cvirec-22-update-database-models
+     - Branch: jayscambler/cvirec-22-update-database-models
      - PR: #23
 
    - CVIREC-23: Clean up unused evaluation files
      - Labels: Technical Debt
-     - Branch: jay/cvirec-23-clean-up-evaluation-files
+     - Branch: jayscambler/cvirec-23-clean-up-evaluation-files
      - PR: #24
 
    ## Pull Requests:

.claude/debugging/lance-map-type-issue.md

@@ -11,7 +11,7 @@
 ## Original Issue Summary
 
 **Issue ID**: CFOS-41  
-**Branch**: `jay/cfos-41-fix-lance-map-type-incompatibility-for-custom_metadata-field`  
+**Branch**: `jayscambler/cfos-41-fix-lance-map-type-incompatibility-for-custom_metadata-field`  
 **Status**: ~~In Progress~~ **RESOLVED**
 
 ### Problem Description

.claude/documentation/modelcontextprotocol/01_overview/index.md

@@ -0,0 +1,122 @@
+# Model Context Protocol Specification
+
+[Model Context Protocol](https://modelcontextprotocol.io/) (MCP) is an open protocol that
+enables seamless integration between LLM applications and external data sources and
+tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating
+custom AI workflows, MCP provides a standardized way to connect LLMs with the context
+they need.
+
+This specification defines the authoritative protocol requirements, based on the
+TypeScript schema in
+[schema.ts](https://github.com/modelcontextprotocol/specification/blob/main/schema/2025-03-26/schema.ts).
+
+For implementation guides and examples, visit
+[modelcontextprotocol.io](https://modelcontextprotocol.io/).
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD
+NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
+interpreted as described in [BCP 14](https://datatracker.ietf.org/doc/html/bcp14)
+\[ [RFC2119](https://datatracker.ietf.org/doc/html/rfc2119)\]
+\[ [RFC8174](https://datatracker.ietf.org/doc/html/rfc8174)\] when, and only when, they
+appear in all capitals, as shown here.
+
+## Overview
+
+MCP provides a standardized way for applications to:
+
+- Share contextual information with language models
+- Expose tools and capabilities to AI systems
+- Build composable integrations and workflows
+
+The protocol uses [JSON-RPC](https://www.jsonrpc.org/) 2.0 messages to establish
+communication between:
+
+- **Hosts**: LLM applications that initiate connections
+- **Clients**: Connectors within the host application
+- **Servers**: Services that provide context and capabilities
+
+MCP takes some inspiration from the
+[Language Server Protocol](https://microsoft.github.io/language-server-protocol/), which
+standardizes how to add support for programming languages across a whole ecosystem of
+development tools. In a similar way, MCP standardizes how to integrate additional context
+and tools into the ecosystem of AI applications.
+
+## Key Details
+
+### Base Protocol
+
+- [JSON-RPC](https://www.jsonrpc.org/) message format
+- Stateful connections
+- Server and client capability negotiation
+
+### Features
+
+Servers offer any of the following features to clients:
+
+- **Resources**: Context and data, for the user or the AI model to use
+- **Prompts**: Templated messages and workflows for users
+- **Tools**: Functions for the AI model to execute
+
+Clients may offer the following feature to servers:
+
+- **Sampling**: Server-initiated agentic behaviors and recursive LLM interactions
+
+### Additional Utilities
+
+- Configuration
+- Progress tracking
+- Cancellation
+- Error reporting
+- Logging
+
+## Security and Trust & Safety
+
+The Model Context Protocol enables powerful capabilities through arbitrary data access
+and code execution paths. With this power comes important security and trust
+considerations that all implementors must carefully address.
+
+### Key Principles
+
+1. **User Consent and Control**
+   - Users must explicitly consent to and understand all data access and operations
+   - Users must retain control over what data is shared and what actions are taken
+   - Implementors should provide clear UIs for reviewing and authorizing activities
+2. **Data Privacy**
+   - Hosts must obtain explicit user consent before exposing user data to servers
+   - Hosts must not transmit resource data elsewhere without user consent
+   - User data should be protected with appropriate access controls
+3. **Tool Safety**
+   - Tools represent arbitrary code execution and must be treated with appropriate
+     caution.
+     - In particular, descriptions of tool behavior such as annotations should be
+       considered untrusted, unless obtained from a trusted server.
+   - Hosts must obtain explicit user consent before invoking any tool
+   - Users should understand what each tool does before authorizing its use
+4. **LLM Sampling Controls**
+   - Users must explicitly approve any LLM sampling requests
+   - Users should control:
+     - Whether sampling occurs at all
+     - The actual prompt that will be sent
+     - What results the server can see
+   - The protocol intentionally limits server visibility into prompts
+
+### Implementation Guidelines
+
+While MCP itself cannot enforce these security principles at the protocol level,
+implementors **SHOULD**:
+
+1. Build robust consent and authorization flows into their applications
+2. Provide clear documentation of security implications
+3. Implement appropriate access controls and data protections
+4. Follow security best practices in their integrations
+5. Consider privacy implications in their feature designs
+
+## Learn More
+
+Explore the detailed specification for each protocol component:
+
+- **Architecture**
+- **Base Protocol**
+- **Server Features**
+- **Client Features**
+- **Contributing**

.claude/documentation/modelcontextprotocol/02_architecture/architecture.md

@@ -0,0 +1,98 @@
+# Architecture
+
+The Model Context Protocol (MCP) follows a client-host-server architecture where each
+host can run multiple client instances. This architecture enables users to integrate AI
+capabilities across applications while maintaining clear security boundaries and
+isolating concerns. Built on JSON-RPC, MCP provides a stateful session protocol focused
+on context exchange and sampling coordination between clients and servers.
+
+## Core Components
+
+### Host
+
+The host process acts as the container and coordinator:
+
+- Creates and manages multiple client instances
+- Controls client connection permissions and lifecycle
+- Enforces security policies and consent requirements
+- Handles user authorization decisions
+- Coordinates AI/LLM integration and sampling
+- Manages context aggregation across clients
+
+### Clients
+
+Each client is created by the host and maintains an isolated server connection:
+
+- Establishes one stateful session per server
+- Handles protocol negotiation and capability exchange
+- Routes protocol messages bidirectionally
+- Manages subscriptions and notifications
+- Maintains security boundaries between servers
+
+A host application creates and manages multiple clients, with each client having a 1:1
+relationship with a particular server.
+
+### Servers
+
+Servers provide specialized context and capabilities:
+
+- Expose resources, tools and prompts via MCP primitives
+- Operate independently with focused responsibilities
+- Request sampling through client interfaces
+- Must respect security constraints
+- Can be local processes or remote services
+
+## Design Principles
+
+MCP is built on several key design principles that inform its architecture and
+implementation:
+
+1. **Servers should be extremely easy to build**
+   - Host applications handle complex orchestration responsibilities
+   - Servers focus on specific, well-defined capabilities
+   - Simple interfaces minimize implementation overhead
+   - Clear separation enables maintainable code
+2. **Servers should be highly composable**
+   - Each server provides focused functionality in isolation
+   - Multiple servers can be combined seamlessly
+   - Shared protocol enables interoperability
+   - Modular design supports extensibility
+3. **Servers should not be able to read the whole conversation, nor "see into" other**
+**servers**
+   - Servers receive only necessary contextual information
+   - Full conversation history stays with the host
+   - Each server connection maintains isolation
+   - Cross-server interactions are controlled by the host
+   - Host process enforces security boundaries
+4. **Features can be added to servers and clients progressively**
+   - Core protocol provides minimal required functionality
+   - Additional capabilities can be negotiated as needed
+   - Servers and clients evolve independently
+   - Protocol designed for future extensibility
+   - Backwards compatibility is maintained
+
+## Capability Negotiation
+
+The Model Context Protocol uses a capability-based negotiation system where clients and
+servers explicitly declare their supported features during initialization. Capabilities
+determine which protocol features and primitives are available during a session.
+
+- Servers declare capabilities like resource subscriptions, tool support, and prompt
+templates
+- Clients declare capabilities like sampling support and notification handling
+- Both parties must respect declared capabilities throughout the session
+- Additional capabilities can be negotiated through extensions to the protocol
+
+Each capability unlocks specific protocol features for use during the session. For
+example:
+
+- Implemented server features must be advertised in the
+server's capabilities
+- Emitting resource subscription notifications requires the server to declare
+subscription support
+- Tool invocation requires the server to declare tool capabilities
+- Sampling requires the client to declare support in its
+capabilities
+
+This capability negotiation ensures clients and servers have a clear understanding of
+supported functionality while maintaining protocol extensibility.

.claude/documentation/modelcontextprotocol/03_base_protocol/01_overview.md

@@ -0,0 +1,123 @@
+# Base Protocol Overview
+
+**Protocol Revision**: 2025-03-26
+
+The Model Context Protocol consists of several key components that work together:
+
+- **Base Protocol**: Core JSON-RPC message types
+- **Lifecycle Management**: Connection initialization, capability negotiation, and
+session control
+- **Server Features**: Resources, prompts, and tools exposed by servers
+- **Client Features**: Sampling and root directory lists provided by clients
+- **Utilities**: Cross-cutting concerns like logging and argument completion
+
+All implementations **MUST** support the base protocol and lifecycle management
+components. Other components **MAY** be implemented based on the specific needs of the
+application.
+
+These protocol layers establish clear separation of concerns while enabling rich
+interactions between clients and servers. The modular design allows implementations to
+support exactly the features they need.
+
+## Messages
+
+All messages between MCP clients and servers **MUST** follow the
+[JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification. The protocol defines
+these types of messages:
+
+### Requests
+
+Requests are sent from the client to the server or vice versa, to initiate an operation.
+
+```json
+{
+  jsonrpc: "2.0";
+  id: string | number;
+  method: string;
+  params?: {
+    [key: string]: unknown;
+  };
+}
+```
+
+- Requests **MUST** include a string or integer ID.
+- Unlike base JSON-RPC, the ID **MUST NOT** be `null`.
+- The request ID **MUST NOT** have been previously used by the requestor within the same
+session.
+
+### Responses
+
+Responses are sent in reply to requests, containing the result or error of the operation.
+
+```json
+{
+  jsonrpc: "2.0";
+  id: string | number;
+  result?: {
+    [key: string]: unknown;
+  }
+  error?: {
+    code: number;
+    message: string;
+    data?: unknown;
+  }
+}
+```
+
+- Responses **MUST** include the same ID as the request they correspond to.
+- **Responses** are further sub-categorized as either **successful results** or
+**errors**. Either a `result` or an `error` **MUST** be set. A response **MUST NOT**
+set both.
+- Results **MAY** follow any JSON object structure, while errors **MUST** include an
+error code and message at minimum.
+- Error codes **MUST** be integers.
+
+### Notifications
+
+Notifications are sent from the client to the server or vice versa, as a one-way message.
+The receiver **MUST NOT** send a response.
+
+```json
+{
+  jsonrpc: "2.0";
+  method: string;
+  params?: {
+    [key: string]: unknown;
+  };
+}
+```
+
+- Notifications **MUST NOT** include an ID.
+
+### Batching
+
+JSON-RPC also defines a means to
+[batch multiple requests and notifications](https://www.jsonrpc.org/specification#batch),
+by sending them in an array. MCP implementations **MAY** support sending JSON-RPC
+batches, but **MUST** support receiving JSON-RPC batches.
+
+## Auth
+
+MCP provides an Authorization framework for use with HTTP.
+Implementations using an HTTP-based transport **SHOULD** conform to this specification,
+whereas implementations using STDIO transport **SHOULD NOT** follow this specification,
+and instead retrieve credentials from the environment.
+
+Additionally, clients and servers **MAY** negotiate their own custom authentication and
+authorization strategies.
+
+For further discussions and contributions to the evolution of MCP's auth mechanisms, join
+us in
+[GitHub Discussions](https://github.com/modelcontextprotocol/specification/discussions)
+to help shape the future of the protocol!
+
+## Schema
+
+The full specification of the protocol is defined as a
+[TypeScript schema](https://github.com/modelcontextprotocol/specification/blob/main/schema/2025-03-26/schema.ts).
+This is the source of truth for all protocol messages and structures.
+
+There is also a
+[JSON Schema](https://github.com/modelcontextprotocol/specification/blob/main/schema/2025-03-26/schema.json),
+which is automatically generated from the TypeScript source of truth, for use with
+various automated tooling.