Javadoc MCP

Javadoc MCP 服务器

一个模型上下文协议（MCP）服务器，提供对Maven Central中的Java文档（Javadocs）和Kotlin文档（KDocs）的访问。该服务器使AI代理能够高效地搜索、下载和查询Java和Kotlin库的文档。

特点/特性

• 🔍（放大镜图标，通常表示搜索、查看细节或调查） 搜索 Maven Central - 在Maven Central上查找任何可用的Java或Kotlin库
• 📦（包裹/箱子） 智能缓存 - 将Javadoc下载到本地 .m2 仓库，仅在未缓存时获取
• 🎯（目标） 细粒度访问 - 多种工具用于广泛搜索和特定文档查询
• ⚡ 闪电符号（在中文语境中通常直接以“⚡”表示，不常翻译为具体文字，但可根据上下文解释为“闪电”或保持符号形式） 快速且异步 - 使用 async/await 构建，以实现最佳性能
• 🛠️（扳手或工具的象征，无具体文字对应，可表示“工具”或“修理”等概念） 综合工具集 - 9种针对不同文档需求的专用工具
• 🎨 表示“美术”或“绘画”的意思，通常用于描述与绘画、艺术创作相关的活动或作品。 Kotlin/Dokka 支持 - 完全支持以Dokka格式生成的Kotlin文档
• 🔄 翻译为中文是“🔄”（注：此符号本身在中文中无特定含义，仅为一个循环或重复的符号，若需表达具体含义，需结合上下文）。不过，若仅从符号本身来看，它常被用来表示循环、重复或持续的动作。在中文语境中，我们可能会直接使用这个符号，或者根据上下文用文字描述其含义，如“循环”、“重复”等。 透明格式处理 - 与传统的Javadoc和Kotlin Dokka完美兼容

可用工具

1. 搜索文物 - 在 Maven Central 上搜索 Java 库
2. 下载_javadoc - 下载并缓存特定版本的Javadoc
3. 列出包（或软件包） - 列出库中的所有包
4. 列出类（或“类列表”） - 列出包或库中的所有类/接口
5. 获取类文档 - 获取特定类的完整文档
6. 获取方法文档 - 获取特定方法的文档
7. 获取软件包摘要 - 获取包级别的文档
8. 在Javadoc中搜索 - 在所有Javadoc文件中搜索术语
9. 根据需要提出更细致的查询

安装

使用紫外线（推荐）

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

# Clone the repository
git clone 
cd javadoc-mcp

# Install dependencies
uv pip install -e .

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

使用 pip

pip install -e .

使用方法

运行服务器

python main.py

或者使其可执行：

chmod +x main.py
./main.py

示例查询

搜索图书馆：

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

下载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(
    group_id="com.fasterxml.jackson.core",
    artifact_id="jackson-core",
    version="2.15.0"
)

列出包中的类：

# 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"
)

获取类文档：

# 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"
)

在javadoc中搜索：

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

配置

服务器使用以下目录：

• Maven 仓库： ~/.m2/repository - 标准 Maven 本地仓库
• 缓存目录： ~/.javadoc-mcp-cache - 服务器元数据的额外缓存

这些目录在首次运行时会自动创建。

建筑学

文档格式支持

这台服务器透明地处理两者 Java Javadoc 并且 Kotlin Dokka（注：Dokka 是 Kotlin 的文档生成工具，类似于 Java 的 Javadoc） 文档格式：

• 传统的Javadoc标准HTML格式，带嵌套目录结构com/example/Class.html)
• Kotlin Dokka（注：Dokka是Kotlin的文档生成工具，此处“Kotlin Dokka”通常指使用Dokka为Kotlin代码生成文档的功能或过程）现代文档格式，包含：

- 基于模块的组织 - URL编码的文件名（例如。， -http-client.html for HttpClient) - 使用字面点（例如。， io.ktor.client/) - 富含增强导航功能的HTML

服务器自动检测格式并从HTML中提取类名 `` 标签，确保无论文档格式如何都能得到准确结果。

缓存策略

1. 检查是否已提取 - 如果javadoc已经提取，使用缓存版本
2. 检查JAR文件是否存在 - 如果 javadoc JAR 文件存在但未解压，则进行解压
3. 从 Maven Central 下载 - 仅当本地不存在时才下载

这确保了网络使用量最小化，并且对于重复查询能够快速响应。

文件组织

Javadoc 按照 Maven 的标准结构存储：

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

发展

运行测试

pytest

代码格式化

# Format code
black .

# Lint code
ruff check .

# Type checking
mypy .

项目结构

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

要求

• Python 3.10或更高版本
• 互联网连接（用于下载Javadoc）
• 每个库约100MB的磁盘空间（用于缓存Javadoc）

依赖项

• fastmcp（该词在中文中没有直接对应的翻译，但根据上下文可理解为“快速多通道处理”或类似含义的技术或方法名称，具体翻译需结合实际应用场景） >= 2.0.0 - MCP服务器框架
• httpx（注：这是一个技术或工具名称，在中文中通常直接保留原名，不进行翻译，表示一种基于HTTP协议的扩展或高级工具） >= 0.27.0 - 异步HTTP客户端
• Beautiful Soup 4 >= 4.12.0 - HTML 解析
• lxml >= 5.0.0 - XML/HTML 解析器
• aiofiles（通常指一个用于异步文件操作的Python库） >= 23.0.0 - 异步文件操作

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件

贡献；做出贡献

欢迎贡献！请随时提交拉取请求。

故障排除

未找到Javadoc

有些工件可能没有发布带有Javadoc的JAR文件。请尝试搜索其他版本或工件。

下载失败

检查您的互联网连接，并在 Maven Central（https://search.maven.org/）上验证该构件是否存在

提取错误

确保您拥有写入权限 ~/.m2/repository 目录。

Kotlin/Dokka 库

Kotlin 库使用 Dokka 格式，其结构与传统的 Javadoc 不同：

• 从HTML中提取类名 `` 标签，而非文件名
• 文件名使用URL编码（例如。， -http-client.html for HttpClient）
• 包目录使用实际的点号而不是斜杠
• 服务器会自动处理这一点，无需特殊配置

如果你在使用 Kotlin 库时遇到问题，请在 Maven Central 上验证库的名称和版本，因为有些 Kotlin 库可能会在不同的 artifact ID 下发布文档。 检查您的互联网连接，并在 https://search.maven.org/ 上验证该构件是否存在于 Maven 中央仓库

提取错误

确保您拥有写入权限以 ~/.m2/repository 目录。