Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
224 lines (173 loc) · 8.91 KB

ARCHITECTURE.md

File metadata and controls

224 lines (173 loc) · 8.91 KB
Raw

Architecture

This document describes the architecture and design decisions of the Solr MCP Server.

Project Structure

The codebase follows a clean, modular architecture organized by functionality:

src/main/java/org/apache/solr/mcp/server/
├── Main.java                           # Application entry point
├── config/                             # Configuration classes
│   ├── SolrConfig.java                # Solr client bean configuration
│   └── SolrConfigurationProperties.java # Solr connection properties
├── search/                             # Search functionality
│   ├── SearchService.java             # MCP tool for searching Solr
│   └── SearchResponse.java            # Search result DTOs
├── indexing/                           # Document indexing functionality
│   ├── IndexingService.java           # MCP tools for indexing documents
│   ├── SolrUpdateXml.java             # Rejects anything but an <add> block before XML is forwarded to Solr
│   └── documentcreator/               # Parsers for the formats Solr cannot parse itself
│       ├── IndexingDocumentCreator.java    # Orchestrator that delegates to format-specific creators
│       ├── JsonDocumentCreator.java        # JSON document parser (implements SolrDocumentCreator)
│       ├── MarkdownDocumentCreator.java    # Markdown document parser (implements SolrDocumentCreator)
│       ├── SolrDocumentCreator.java        # Common interface for document creators
│       ├── FieldNameSanitizer.java         # Field name sanitization utility
│       └── DocumentProcessingException.java # Indexing exceptions
└── collection/                           # Collection management functionality
    ├── CollectionService.java         # MCP tools for collection operations
    ├── SchemaService.java             # MCP tool for schema retrieval
    ├── CollectionUtils.java           # Collection utility methods
    └── Dtos.java                      # Collection-related DTOs (records)

Key Components

MCP Tools

Service classes annotated with @McpTool expose functionality to AI assistants:

  • SearchService - Search queries with filtering, faceting, and pagination
  • IndexingService - Document indexing with support for JSON, CSV, and XML formats
  • CollectionService - Collection management (list, stats, health checks)
  • SchemaService - Schema introspection

Configuration

Spring Boot configuration using properties files:

  • application.properties - Default configuration
  • application-stdio.properties - STDIO transport profile
  • application-http.properties - HTTP transport profile

Document Creators

Server-side parsing exists only for JSON and Markdown, the formats Solr's update handlers do not accept directly:

  • Automatically sanitizes field names to comply with Solr schema requirements
  • Supports nested JSON structures and multi-valued fields
  • Delegation via service composition (IndexingDocumentCreator) to the appropriate format-specific creator

CSV and Solr update XML are forwarded to Solr as-is, field names as given. The only server-side step is SolrUpdateXml, which rejects any XML root other than <add> so the indexing tool cannot carry <delete> or <commit>.

DTOs

Java record types used as data transfer objects:

  • No Lombok dependency; the record declaration is the whole definition
  • Designed for straightforward serialization/deserialization
  • Records are immutable by construction, so the response types handed to MCP clients cannot be mutated after they are built

Design Decisions

Why Spring AI MCP?

Spring AI MCP provides a robust framework for implementing the Model Context Protocol with:

  • Built-in transport layer support (STDIO and HTTP)
  • Annotation-based tool registration
  • Spring Boot integration for configuration and dependency injection

Why Jib instead of Spring Boot Buildpacks?

STDIO Mode Compatibility: Docker images built with Spring Boot Buildpacks output logs and diagnostic information to stdout, which interferes with the MCP protocol's STDIO transport. The MCP protocol requires a clean stdout channel for protocol messages.

Additional Jib benefits:

  • Clean stdout: No pollution of protocol messages
  • No Docker daemon required: Can build images without Docker installed
  • Faster builds: Layered image building with better caching
  • Smaller images: More efficient layer organization
  • Multi-platform support: Easy cross-platform image building for amd64 and arm64

Transport Modes

STDIO (Recommended for Claude Desktop)

  • Communication via standard input/output streams
  • No network exposure
  • OS-level process isolation
  • Secure for local deployments

HTTP (For MCP Inspector / Remote Access)

  • RESTful endpoints using Spring Web
  • Streamable HTTP transport
  • Requires additional security measures for production
  • Useful for testing and remote deployments

Document Processing

The document creator pattern allows for:

  • Extensibility: Easy to add new format parsers
  • Testability: Each creator can be tested independently
  • Field Sanitization: Automatic conversion of field names to Solr-compatible format
  • Explicit Format Selection: Separate methods for JSON/CSV/XML (no automatic detection)

Error Handling

  • Custom exceptions for domain-specific errors
  • Proper error messages propagated to MCP clients
  • Validation at tool entry points

Testing Architecture

Unit Tests

  • Test individual components in isolation
  • Mock external dependencies (Solr, Spring beans)
  • Fast execution for quick feedback

Integration Tests

  • Use Testcontainers for real Solr instances
  • Test end-to-end workflows
  • Verify Docker image functionality

Test Structure

src/test/java/org/apache/solr/mcp/server/
├── MainTest.java                      # Application bootstrap
├── McpToolRegistrationTest.java       # MCP tool registration tests
├── McpClientIntegrationTest.java      # MCP workflow over the in-process client
├── McpClientStdioIntegrationTest.java # MCP workflow against `java -jar` over STDIO
├── BuildInfoReader.java               # Test utility for build metadata
├── SampleClient.java                  # Example MCP client
├── search/
│   ├── SearchServiceTest.java             # Unit tests
│   └── SearchServiceIntegrationTest.java  # Testcontainers
├── indexing/
│   ├── IndexingServiceTest.java
│   ├── IndexingServiceIntegrationTest.java
│   ├── SolrUpdateXmlTest.java             # <add>-only gate
│   ├── MarkdownIndexingTest.java
│   └── ShowsSampleDataIntegrationTest.java  # JSON/CSV/XML parity
├── collection/
│   ├── CollectionServiceTest.java
│   ├── CollectionUtilsTest.java
│   ├── CollectionServiceIntegrationTest.java
│   └── ConferenceEndToEndIntegrationTest.java
├── schema/
│   ├── SchemaServiceTest.java
│   └── SchemaServiceIntegrationTest.java
├── config/
│   ├── JsonResponseParserTest.java
│   ├── SolrConfigUrlNormalizationTest.java
│   └── SolrConfigIntegrationTest.java
├── observability/
│   ├── DistributedTracingTest.java
│   └── OtlpExportIntegrationTest.java
└── containerization/                  # @Tag("docker-integration") only
    ├── DockerImageStdioIntegrationTest.java
    ├── DockerImageMcpClientStdioIntegrationTest.java
    └── DockerImageHttpIntegrationTest.java

Dependency Management

All dependencies are managed via Gradle version catalogs in gradle/libs.versions.toml:

  • Centralized version management
  • Easy upgrades and consistency
  • Clear dependency organization

Configuration Properties

Solr Connection

  • SOLR_URL: Solr instance URL (default: http://localhost:8983/solr/)
  • SOLR_USERNAME: HTTP Basic Authentication username (optional; required together with SOLR_PASSWORD)
  • SOLR_PASSWORD: HTTP Basic Authentication password (optional; required together with SOLR_USERNAME)

Transport Mode

  • PROFILES: Set to stdio or http to select transport mode

Docker Compose

  • SPRING_DOCKER_COMPOSE_ENABLED: Enable/disable Docker Compose integration

Future Considerations

Potential Enhancements

  1. Authentication & Authorization

    • Role-based access control (OAuth2 resource-server support and bearer-token authentication for HTTP mode are already implemented — see security/HttpSecurityConfiguration.)

  2. Additional Tools

    • Bulk operations
    • Query suggestions
    • Analytics and reporting

  3. Performance

    • Response streaming for large result sets
    • Query caching
    • Connection pooling optimization

  4. Monitoring

    • Metrics collection
    • Health checks
    • Performance monitoring

  5. Multi-Solr Support

    • Connect to multiple Solr instances
    • Cross-cluster operations