feat: MVP MCP server with documentation and source tools #10

Merged

mprihoda merged 62 commits from JMC-1 into main

2026-01-02 12:40:41 +00:00

mprihoda commented

2026-01-02 12:35:47 +00:00

(Migrated from github.com)

Summary

Complete MVP implementation of an MCP server that fetches Javadoc/Scaladoc and source code for JVM libraries from Maven Central.

Features

get_documentation tool: Fetches Javadoc HTML for Java classes or Scaladoc for Scala classes
get_source tool: Fetches source code (.java or .scala) for JVM classes
Scala support: Handles :: coordinate syntax, configurable Scala version (2.12, 2.13, 3)
Error handling: Helpful multi-line error messages with suggestions
Caching: LRU in-memory cache with configurable size (CACHE_MAX_SIZE_MB)

Performance

First request: ~3-5s (artifact download)
Cached request: <100ms (97% improvement)
Coursier file cache helps subsequent requests for same artifact

Phase PRs

#2, #3: Phase 1 - Fetch Javadoc HTML for Java class
#4: Phase 2 - Fetch source code for Java class
#5: Phase 3 - Fetch Scaladoc HTML for Scala class
#6: Phase 4 - Fetch source code for Scala class
#7: Phase 5 - Handle missing artifacts gracefully
#8: Phase 6 - Handle missing classes within artifacts
#9: Phase 7 - In-memory caching for repeated lookups

Architecture

Presentation Layer (McpServer, ToolDefinitions)
       ↓
Caching Layer (CachedDocumentationService, CachedSourceCodeService, LRUCache)
       ↓
Application Layer (DocumentationService, SourceCodeService)
       ↓
Infrastructure Layer (CoursierArtifactRepository, JarFileReader, TastySourceResolver)

Testing

121 tests total
Unit tests: Domain logic, cache behavior, thread safety
Integration tests: Real Maven Central artifacts
E2E tests: Full HTTP MCP protocol flow, performance verification

Configuration

# Run with defaults (100MB cache)
scala-cli run .

# Custom cache size
CACHE_MAX_SIZE_MB=200 scala-cli run .

# Custom port
PORT=9000 scala-cli run .

Usage Example

{
  "method": "tools/call",
  "params": {
    "name": "get_documentation",
    "arguments": {
      "coordinates": "org.slf4j:slf4j-api:2.0.9",
      "className": "org.slf4j.Logger"
    }
  }
}

Closes JMC-1

🤖 Generated with Claude Code

## Summary Complete MVP implementation of an MCP server that fetches Javadoc/Scaladoc and source code for JVM libraries from Maven Central. ### Features - **get_documentation** tool: Fetches Javadoc HTML for Java classes or Scaladoc for Scala classes - **get_source** tool: Fetches source code (.java or .scala) for JVM classes - **Scala support**: Handles `::` coordinate syntax, configurable Scala version (2.12, 2.13, 3) - **Error handling**: Helpful multi-line error messages with suggestions - **Caching**: LRU in-memory cache with configurable size (CACHE_MAX_SIZE_MB) ### Performance - First request: ~3-5s (artifact download) - Cached request: <100ms (97% improvement) - Coursier file cache helps subsequent requests for same artifact ## Phase PRs - #2, #3: Phase 1 - Fetch Javadoc HTML for Java class - #4: Phase 2 - Fetch source code for Java class - #5: Phase 3 - Fetch Scaladoc HTML for Scala class - #6: Phase 4 - Fetch source code for Scala class - #7: Phase 5 - Handle missing artifacts gracefully - #8: Phase 6 - Handle missing classes within artifacts - #9: Phase 7 - In-memory caching for repeated lookups ## Architecture ``` Presentation Layer (McpServer, ToolDefinitions) ↓ Caching Layer (CachedDocumentationService, CachedSourceCodeService, LRUCache) ↓ Application Layer (DocumentationService, SourceCodeService) ↓ Infrastructure Layer (CoursierArtifactRepository, JarFileReader, TastySourceResolver) ``` ## Testing - **121 tests total** - Unit tests: Domain logic, cache behavior, thread safety - Integration tests: Real Maven Central artifacts - E2E tests: Full HTTP MCP protocol flow, performance verification ## Configuration ```bash # Run with defaults (100MB cache) scala-cli run . # Custom cache size CACHE_MAX_SIZE_MB=200 scala-cli run . # Custom port PORT=9000 scala-cli run . ``` ## Usage Example ```json { "method": "tools/call", "params": { "name": "get_documentation", "arguments": { "coordinates": "org.slf4j:slf4j-api:2.0.9", "className": "org.slf4j.Logger" } } } ``` Closes JMC-1 🤖 Generated with [Claude Code](https://claude.com/claude-code)