Skip to content

Commit 0cfd529

Browse files
aschemanclaude
ascheman
and
claude
committed
Restructure documentation with docs/index.adoc entry point
- Simplify README.adoc to minimal quick-start format - Add docs/index.adoc as project documentation hub - Link to all existing docs, ADRs, and umbrella project 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 3f0a122 commit 0cfd529

2 files changed

Lines changed: 119 additions & 67 deletions

File tree

‎README.adoc‎

Lines changed: 21 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -14,97 +14,51 @@
1414
// limitations under the License.
1515
//
1616

17-
= mail-mcp: Maven Mailing List MCP Server
18-
:toc:
19-
:toclevels: 2
17+
= mail-mcp
2018

21-
== Overview
22-
23-
*mail-mcp* is an MCP (Model Context Protocol) server for accessing and analyzing Apache Maven mailing list archives.
24-
It provides tools to retrieve and process historical email discussions from Maven mailing lists, primarily dev@maven.apache.org.
25-
26-
== Status
27-
28-
🚧 *Early Development* - Data retrieval and parsing infrastructure implemented.
29-
MCP server implementation in progress.
19+
MCP server for accessing and analyzing Apache Maven mailing list archives.
3020

3121
== Quick Start
3222

3323
=== Prerequisites
3424

35-
Python 3.11+:: Must be installed
36-
Poetry:: Dependency manager (install via `pipx install poetry`)
37-
Docker Desktop:: For running Elasticsearch
25+
* Python 3.11+
26+
* Docker Desktop (for Elasticsearch)
3827

3928
=== Setup
4029

4130
[source,bash]
4231
----
43-
# Configure poetry to use in-project virtual environment
44-
poetry config virtualenvs.in-project true
45-
46-
# Install dependencies (creates .venv/ automatically)
47-
poetry install
48-
----
49-
50-
=== Retrieve Mailing List Data
32+
# Install dependencies
33+
pip install -e ".[dev]"
5134
52-
[source,bash]
53-
----
54-
# Download a specific month from dev@maven.apache.org
55-
poetry run retrieve-mbox --date 2024-10
35+
# Start Elasticsearch
36+
docker compose up -d elasticsearch
5637
57-
# Download from a different mailing list
58-
poetry run retrieve-mbox --date 2024-10 --list users@maven.apache.org
38+
# Download mailing list data
39+
retrieve-mbox --date 2024-10
5940
60-
# Show help
61-
poetry run retrieve-mbox --help
41+
# Index the data
42+
index-mbox data/dev/*.mbox
6243
----
6344

64-
The script downloads mbox files from the Apache Lists API and saves them as `YYYY-MM.mbox` in the current directory.
65-
66-
=== Start Infrastructure
45+
=== Run MCP Server
6746

6847
[source,bash]
6948
----
70-
# Start Elasticsearch and Kibana for development
71-
docker compose up -d elasticsearch kibana
72-
73-
# Check health
74-
curl http://localhost:9200/_cluster/health
75-
76-
# Access Kibana web UI for data exploration
77-
open http://localhost:5601
49+
maven-mail-mcp
7850
----
7951

8052
== Documentation
8153

82-
Development guide:: xref:docs/development.adoc[Development workflow, project structure, tools]
83-
MCP Server:: xref:docs/mcp-server.adoc[Setting up and using the MCP server with Claude Desktop]
84-
Docker setup:: xref:docs/docker.adoc[Running Elasticsearch and services with Docker]
85-
Data management:: xref:docs/data-management.adoc[Working with mbox files and archives]
86-
Roadmap:: xref:docs/roadmap.adoc[Implementation status and planned features]
87-
Architecture decisions:: xref:docs/adr/[ADRs documenting key technical decisions]
88-
89-
== Part of maven-mcps
54+
See xref:docs/index.adoc[Documentation] for:
9055

91-
This project is one MCP server within the maven-mcps umbrella project, which contains multiple MCP servers for Apache Maven support.
56+
* Development guide and CI
57+
* Docker setup
58+
* MCP server configuration
59+
* Data management
60+
* Architecture decisions
9261

9362
== License
9463

95-
This project is licensed under the Apache License 2.0.
96-
See the xref:LICENSE[LICENSE] file for details.
97-
98-
Copyright 2025 The Apache Software Foundation
99-
100-
Licensed under the Apache License, Version 2.0 (the "License");
101-
you may not use this file except in compliance with the License.
102-
You may obtain a copy of the License at
103-
104-
http://www.apache.org/licenses/LICENSE-2.0
105-
106-
Unless required by applicable law or agreed to in writing, software
107-
distributed under the License is distributed on an "AS IS" BASIS,
108-
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
109-
See the License for the specific language governing permissions and
110-
limitations under the License.
64+
Apache License 2.0 - See xref:../LICENSE[LICENSE] for details.

‎docs/index.adoc‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
//
2+
// Copyright 2025 The Apache Software Foundation
3+
//
4+
// Licensed under the Apache License, Version 2.0 (the "License");
5+
// you may not use this file except in compliance with the License.
6+
// You may obtain a copy of the License at
7+
//
8+
// http://www.apache.org/licenses/LICENSE-2.0
9+
//
10+
// Unless required by applicable law or agreed to in writing, software
11+
// distributed under the License is distributed on an "AS IS" BASIS,
12+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
// See the License for the specific language governing permissions and
14+
// limitations under the License.
15+
//
16+
17+
= mail-mcp Documentation
18+
:toc:
19+
:toclevels: 2
20+
21+
== Overview
22+
23+
*mail-mcp* is an MCP (Model Context Protocol) server for accessing and analyzing Apache Maven mailing list archives.
24+
It provides tools to retrieve and process historical email discussions from Maven mailing lists, primarily dev@maven.apache.org.
25+
26+
== Status
27+
28+
*Early Development* - Data retrieval and parsing infrastructure implemented.
29+
MCP server implementation in progress.
30+
31+
== Quick Start
32+
33+
See xref:../README.adoc[README] for prerequisites and initial setup.
34+
35+
== Documentation
36+
37+
=== Getting Started
38+
39+
xref:development.adoc[Development Guide]::
40+
Development workflow, project structure, virtual environment setup, and CI.
41+
42+
xref:docker.adoc[Docker Setup]::
43+
Running Elasticsearch and related services with Docker Compose.
44+
45+
=== Using the MCP Server
46+
47+
xref:mcp-server.adoc[MCP Server Guide]::
48+
Setting up and using the MCP server with Claude Desktop.
49+
50+
xref:data-management.adoc[Data Management]::
51+
Working with mbox files, downloading archives, and indexing.
52+
53+
=== Analysis and Testing
54+
55+
xref:analysis-scripts.adoc[Analysis Scripts]::
56+
Scripts for analyzing and exploring the email archives.
57+
58+
xref:testing-mcp.adoc[Testing MCP]::
59+
Testing the MCP server implementation.
60+
61+
=== Project Status
62+
63+
xref:roadmap.adoc[Roadmap]::
64+
Implementation status and planned features.
65+
66+
== Architecture Decisions
67+
68+
Architecture Decision Records document key technical decisions:
69+
70+
[cols="1,3,1"]
71+
|===
72+
|ADR |Title |Status
73+
74+
|xref:adr/0001-storage-and-access-strategy.adoc[ADR-0001]
75+
|Storage and Access Strategy (Elasticsearch)
76+
|Accepted
77+
78+
|xref:adr/0002-technology-stack.adoc[ADR-0002]
79+
|Technology Stack (Python 3.11+)
80+
|Accepted
81+
82+
|xref:adr/0003-archive-url-resolution.adoc[ADR-0003]
83+
|Archive URL Resolution (Pony Mail)
84+
|Accepted
85+
86+
|xref:adr/0004-lenient-mypy-configuration.adoc[ADR-0004]
87+
|Lenient mypy Configuration for MVP
88+
|Accepted
89+
90+
|===
91+
92+
== Part of Maven MCPs
93+
94+
This project is one MCP server within the maven-mcps umbrella project.
95+
96+
* xref:../../docs/index.adoc[Maven MCPs Documentation] - umbrella project docs
97+
* xref:../../docs/usage/index.adoc[Usage Documentation] - using MCPs together
98+
* xref:../../docs/external/index.adoc[External MCPs] - third-party MCP servers

0 commit comments

Comments
 (0)