javadoc-mcp

jermeyyy/javadoc-mcp

3.2

If you are the rightful owner of javadoc-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A Model Context Protocol (MCP) server that provides access to Javadocs and KDocs from Maven Central, enabling efficient search, download, and query of Java and Kotlin library documentation.

Tools
8
Resources
0
Prompts
0

Javadoc MCP Server

A Model Context Protocol (MCP) server that provides access to Javadocs and KDocs from Maven Central. This server allows AI agents to search, download, and query Java and Kotlin library documentation efficiently.

Features

  • 🔍 Search Maven Central - Find any Java or Kotlin library available on Maven Central
  • 📦 Smart Caching - Downloads javadocs to local .m2 repository, only fetches if not cached
  • 🎯 Granular Access - Multiple tools for broad searches and specific documentation queries
  • ⚡ Fast & Async - Built with async/await for optimal performance
  • 🛠️ Comprehensive Toolset - 9 specialized tools for different documentation needs
  • 🎨 Kotlin/Dokka Support - Full support for Kotlin documentation in Dokka format
  • 🔄 Transparent Format Handling - Works seamlessly with both traditional Javadoc and Kotlin Dokka

Tools Available

  1. search_artifact - Search for Java libraries on Maven Central
  2. download_javadoc - Download and cache javadoc for a specific version
  3. list_packages - List all packages in a library
  4. list_classes - List all classes/interfaces in a package or library
  5. get_class_documentation - Get full documentation for a specific class
  6. get_method_documentation - Get documentation for a specific method
  7. get_package_summary - Get package-level documentation
  8. search_in_javadoc - Search for terms across all javadoc files
  9. More granular queries as needed

Installation

Using uv (Recommended)

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone <your-repo-url>
cd javadoc-mcp

# Install dependencies
uv pip install -e .

# For development
uv pip install -e ".[dev]"

Using pip

pip install -e .

Usage

Running the Server

python main.py

Or make it executable:

chmod +x main.py
./main.py

Example Queries

Search for a library:

search_artifact(query="jackson-core", max_results=5)
# Or search for Kotlin libraries
search_artifact(query="ktor-client", max_results=5)

Download javadoc:

# Java library
download_javadoc(
    group_id="com.fasterxml.jackson.core",
    artifact_id="jackson-core",
    version="2.15.0"
)

# Kotlin library (automatically handles Dokka format)
download_javadoc(
    group_id="io.ktor",
    artifact_id="ktor-client-core",
    version="3.3.1"
)

List packages:

list_packages(
    group_id="com.fasterxml.jackson.core",
    artifact_id="jackson-core",
    version="2.15.0"
)

List classes in a package:

# Works with both Java and Kotlin libraries
list_classes(
    group_id="io.ktor",
    artifact_id="ktor-client-core",
    version="3.3.1",
    package="io.ktor.client"
)

Get class documentation:

# Java class
get_class_documentation(
    group_id="com.fasterxml.jackson.core",
    artifact_id="jackson-core",
    version="2.15.0",
    class_name="com.fasterxml.jackson.core.JsonParser"
)

# Kotlin class (Dokka format handled automatically)
get_class_documentation(
    group_id="io.ktor",
    artifact_id="ktor-client-core",
    version="3.3.1",
    class_name="io.ktor.client.HttpClient"
)

Search within javadoc:

search_in_javadoc(
    group_id="com.fasterxml.jackson.core",
    artifact_id="jackson-core",
    version="2.15.0",
    search_term="parse",
    max_results=10
)

Configuration

The server uses the following directories:

  • Maven Repository: ~/.m2/repository - Standard Maven local repository
  • Cache Directory: ~/.javadoc-mcp-cache - Additional cache for server metadata

These directories are created automatically on first run.

Architecture

Documentation Format Support

This server transparently handles both Java Javadoc and Kotlin Dokka documentation formats:

  • Traditional Javadoc: Standard HTML format with nested directory structure (com/example/Class.html)
  • Kotlin Dokka: Modern documentation format with:
    • Module-based organization
    • URL-encoded filenames (e.g., -http-client.html for HttpClient)
    • Package directories using literal dots (e.g., io.ktor.client/)
    • Rich HTML with enhanced navigation

The server automatically detects the format and extracts class names from HTML <title> tags, ensuring accurate results regardless of the documentation format.

Caching Strategy

  1. Check if extracted - If javadoc is already extracted, use cached version
  2. Check if JAR exists - If javadoc JAR exists but not extracted, extract it
  3. Download from Maven Central - Only download if not present locally

This ensures minimal network usage and fast response times for repeated queries.

File Organization

Javadocs are stored following Maven's standard structure:

~/.m2/repository/
  └── {group.id.path}/
      └── {artifact-id}/
          └── {version}/
              ├── {artifact-id}-{version}-javadoc.jar
              └── javadoc-extracted/
                  └── [extracted javadoc HTML files]

Development

Running Tests

pytest

Code Formatting

# Format code
black .

# Lint code
ruff check .

# Type checking
mypy .

Project Structure

javadoc-mcp/
├── main.py              # Main MCP server implementation
├── pyproject.toml       # Project configuration and dependencies
├── README.md           # This file
└── tests/              # Test suite (to be added)

Requirements

  • Python 3.10 or higher
  • Internet connection (for downloading javadocs)
  • ~100MB disk space per library (for cached javadocs)

Dependencies

  • fastmcp >= 2.0.0 - MCP server framework
  • httpx >= 0.27.0 - Async HTTP client
  • beautifulsoup4 >= 4.12.0 - HTML parsing
  • lxml >= 5.0.0 - XML/HTML parser
  • aiofiles >= 23.0.0 - Async file operations

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Troubleshooting

Javadoc not found

Some artifacts may not have javadoc JARs published. Try searching for a different version or artifact.

Download failures

Check your internet connection and verify the artifact exists on Maven Central at https://search.maven.org/

Extraction errors

Ensure you have write permissions to ~/.m2/repository directory.

Kotlin/Dokka Libraries

Kotlin libraries use Dokka format which has a different structure than traditional Javadoc:

  • Class names are extracted from HTML <title> tags, not filenames
  • Filenames use URL encoding (e.g., -http-client.html for HttpClient)
  • Package directories use literal dots instead of slashes
  • The server handles this automatically - no special configuration needed

If you encounter issues with Kotlin libraries, verify the artifact name and version on Maven Central, as some Kotlin libraries may publish documentation under different artifact IDs. Check your internet connection and verify the artifact exists on Maven Central at https://search.maven.org/

Extraction errors

Ensure you have write permissions to ~/.m2/repository directory.