ADR-0002: External MCP Server Documentation

Status

Proposed

Context

The maven-mcps project develops internal MCP servers (like mail-mcp) to support Apache Maven workflows. However, we also consume third-party MCP servers to access external services such as GitHub, Atlassian (Jira/Confluence), and others.

Key considerations:

External MCPs provide valuable capabilities we don’t need to develop ourselves
Multiple implementations often exist for the same service (e.g., several Jira MCPs)
Configuration, authentication, and deployment requirements vary significantly
Research findings should be preserved to avoid repeated evaluation effort
Clear distinction needed between what we develop vs. what we consume

Decision

We will maintain a dedicated docs/external/ directory to document external MCP servers.

Directory Structure

docs/
├── adr/                      # Architecture Decision Records
└── external/                 # External MCP documentation
    ├── README.adoc           # Purpose and guidelines
    ├── index.adoc            # Catalog of all documented external MCPs
    └── <service>-mcps.adoc   # Detailed docs per service category

Documentation Requirements

Each external MCP evaluation should document:

All discovered alternatives (not just the chosen one)
Research date (to indicate when information was last verified)
Comparison matrix with relevant criteria
Deployment requirements (Cloud vs. Server/Data Center)
Authentication methods (API tokens, PAT, OAuth)
Known limitations and caveats
Practical experience notes from actual usage

Distinction from Internal MCPs

Internal MCPs (our projects): Developed and maintained within this repository. Have their own subdirectory with source code. Documented via README.adoc and docs/ within their subdirectory.
External MCPs (third-party): Developed and maintained by others. We only document configuration and usage. Cataloged in docs/external/.

Consequences

Positive

Knowledge preservation: Research findings are retained for future reference.
Comparison support: Alternative implementations documented side-by-side.
Onboarding: New team members can quickly understand available integrations.
Decision transparency: Clear record of why specific MCPs were chosen.
Reduced duplication: Avoid re-evaluating the same options repeatedly.