docs(readme): expand with install, config, run, and dev sections

will-fawcett · will-fawcett · commit bdf0633d59ed · 2026-04-28T11:10:52.000+01:00
Replace the one-line stub with: alpha/WIP banner, the list of MCP
tools the server registers, install instructions (including
submodule init), env var table for EVE_EMAIL / EVE_PASSWORD /
EVE_BASE_URL, the stdio run command, and pre-commit setup.

Addresses the v0.0.1 README ask from the collaborator's release
checklist.
diff --git a/README.md b/README.md
@@ -1,4 +1,78 @@
 # EVE MCP
 
-An MCP server for EVE.
+An [MCP](https://modelcontextprotocol.io/) server that exposes the
+[EVE](https://eve-chat.chat) Earth Observation chat API as a set of MCP
+tools.
 
+> **Status: alpha (v0.0.1) — work in progress.** APIs, tool names, and
+> wire formats may change without notice. Not yet recommended for
+> production use.
+
+## Tools
+
+The server registers the following MCP tools:
+
+- `query_eve` — query the EVE RAG system and return the assembled answer
+- `list_eve_collections` — list publicly available document collections
+- `check_eve_health` — unauthenticated health check against the EVE API
+- `extract_factuality_issues` — analyze a Google Earth Engine Python
+  script and surface scientific assumptions worth verifying
+- `assess_factuality_issue` — produce an expert-style assessment of an
+  issue raised against a GEE script
+
+## Installation
+
+The project uses [Poetry](https://python-poetry.org/) and a Git
+submodule for the upstream `eve-api` client.
+
+```bash
+git clone --recurse-submodules https://github.com/<org>/eve-mcp.git
+cd eve-mcp
+poetry install
+```
+
+If you cloned without `--recurse-submodules`:
+
+```bash
+git submodule update --init --recursive
+```
+
+Supported Python versions: 3.11–3.14.
+
+## Configuration
+
+The server authenticates to EVE on first tool invocation using the
+following environment variables:
+
+| Variable        | Required | Default                       | Purpose                          |
+| --------------- | -------- | ----------------------------- | -------------------------------- |
+| `EVE_EMAIL`     | yes      | —                             | EVE account email                |
+| `EVE_PASSWORD`  | yes      | —                             | EVE account password             |
+| `EVE_BASE_URL`  | no       | `https://api.eve-chat.chat`   | EVE API base URL                 |
+
+## Running the server
+
+Over stdio (the standard MCP transport):
+
+```bash
+poetry run python -m eve_mcp.server
+```
+
+## Development
+
+Install the pre-commit hooks once:
+
+```bash
+poetry run pre-commit install
+```
+
+Run the full hook suite (black, isort, mypy, pylint, pytest+coverage)
+against all files:
+
+```bash
+poetry run pre-commit run --all-files
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
