# MCP EcoTaxa

A standalone local MCP server for querying a read-only EcoTaxa cache from any
MCP-compatible agent.

Each person runs their own container and local cache. No NeoLab server, IDEA
instance, or shared cache is required.

For a plain-language overview of what an agent can do with this MCP, read
[CAPABILITIES.md](CAPABILITIES.md).

## Quick Start

Requirements: Docker Desktop and an MCP-compatible agent such as Codex, Claude
Code, or Copilot. A validated cache snapshot is downloaded from this
repository's GitHub release. You do not need an EcoTaxa account to explore it.

### 1. Clone

```bash
git clone https://github.com/TidianeCisse777/mcp-ecotaxa.git
cd mcp-ecotaxa
cp .env.example .env
```

Do not change `.env` for a first exploration: consumer mode and the default
cache release are already configured.

Optional capabilities require adding a private value to your local `.env`;
they are not needed to explore the released cache:

- EcoPart enrichment: `ECOPART_TOKEN`, or `ECOTAXA_USERNAME` and
  `ECOTAXA_PASSWORD`.
- Access to a private cache release: `ECOTAXA_CACHE_RELEASE_TOKEN`.

### Use Your Own EcoTaxa Cache

Instead of the shared released snapshot, you can build a personal local cache
from the EcoTaxa projects your account can access. Add the following to your
private `.env`:

```dotenv
ECOTAXA_CACHE_MODE=publisher
ECOTAXA_TOKEN=your-ecotaxa-token
ECOTAXA_CACHE_AUTO_PUBLISH=false
```

Publisher mode uses a Docker volume separate from the released consumer cache.
It is refreshed from EcoTaxa and is never uploaded to this repository. Use
`ECOTAXA_USERNAME` and
`ECOTAXA_PASSWORD` instead of `ECOTAXA_TOKEN` only when token authentication
is unavailable.

### 2. Start

```bash
docker compose up --build -d
curl http://localhost:8001/health
```

On its first start, the container downloads and verifies the SQLite snapshot.
It is ready when the response contains `samples_indexed > 0`,
`projects_indexed > 0`, and `last_sync_status: "ok"`.

### 3. Get the Token

When `MCP_AUTH_TOKEN` is empty (the default), the container creates a durable
token on its first start. Retrieve it once:

```bash
docker compose exec ecotaxa-mcp cat /app/cache/.mcp_auth_token
```

Keep it private: your agent uses this secret to connect to the MCP server.

### 4. Connect Your Agent

Choose the relevant section below. Every configuration uses the same local URL
and the token from step 3.

To follow startup in detail, use a second terminal:

```bash
docker compose logs -f ecotaxa-mcp
```

## Connecting an Agent

The container listens locally at `http://localhost:8001/mcp` using
**Streamable HTTP**. MCP configuration is a one-time manual step for each
agent host.

### Codex

Define the secret in the environment that starts Codex:

```bash
export ECOTAXA_MCP_TOKEN='the-value-from-MCP_AUTH_TOKEN'
```

Add this to `~/.codex/config.toml`:

```toml
[mcp_servers.ecotaxa]
url = "http://localhost:8001/mcp"
bearer_token_env_var = "ECOTAXA_MCP_TOKEN"
```

Restart Codex. The `ecotaxa` server and its tools then appear in the session.

### Claude Code

```bash
export ECOTAXA_MCP_TOKEN='the-value-from-MCP_AUTH_TOKEN'
claude mcp add --transport http \
  --header "Authorization: Bearer $ECOTAXA_MCP_TOKEN" \
  ecotaxa http://localhost:8001/mcp
```

The command registers the server in Claude Code. In a chat, ask: “Use MCP
EcoTaxa to …”.

### GitHub Copilot CLI

```bash
export ECOTAXA_MCP_TOKEN='the-value-from-MCP_AUTH_TOKEN'
copilot mcp add --transport http \
  --header "Authorization: Bearer $ECOTAXA_MCP_TOKEN" \
  ecotaxa http://localhost:8001/mcp
```

The server is registered in `~/.copilot/mcp-config.json`. Then ask Copilot
CLI: “Use MCP EcoTaxa to explore the available samples …”.

### GitHub Copilot Chat in VS Code

In VS Code, use **MCP: Open User Configuration** or create
`.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "ecotaxa": {
      "type": "http",
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer ${input:ecotaxa-mcp-token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "ecotaxa-mcp-token",
      "description": "MCP EcoTaxa token",
      "password": true
    }
  ]
}
```

VS Code asks for the token at first startup and stores it securely.

### Copilot Cloud Agent on GitHub.com

The locally cloned server cannot be used by a Copilot cloud agent: `localhost`
refers to its GitHub environment, not your computer. Deploy the MCP behind an
HTTPS URL reachable from the cloud. Then, in **Settings → Copilot → MCP
servers** for the repository, declare that HTTP server and an agent secret
named `COPILOT_MCP_ECOTAXA_TOKEN`:

```json
{
  "mcpServers": {
    "ecotaxa": {
      "type": "http",
      "url": "https://your-mcp.example/mcp",
      "headers": {
        "Authorization": "Bearer $COPILOT_MCP_ECOTAXA_TOKEN"
      },
      "tools": ["*"]
    }
  }
}
```

Copilot cloud agents use MCP tools but not MCP prompts. Add the EcoTaxa
navigation rules to the agent instructions as well.

### Other MCP Clients

For Cursor or another client that accepts an HTTP MCP declaration, add the
equivalent configuration below, replacing the token:

```json
{
  "mcpServers": {
    "ecotaxa": {
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_AUTH_TOKEN"
      }
    }
  }
}
```

If your agent runs in another Docker container, `localhost` refers to that
container rather than the MCP. Put both containers on the same Docker network
and use `http://ecotaxa-mcp:8001/mcp`, or use
`host.docker.internal:8001` when the runtime supports it.

## What the Server Provides

The server is strictly read-only. It does not modify EcoTaxa, write to
projects, or download a complete EcoTaxa object archive. Its local cache
supports filtering, joining, counting, grouping, and ranking samples.

The available tools are:

- `list_tables` and `describe_table` to inspect the schema when needed;
- `read_query` for read-only SQL exploration;
- `cache_status` to inspect cache freshness;
- `export_query_tsv` to return a selected result as TSV;
- `enrich_ecopart` for an EcoTaxa object TSV joined with EcoPart;
- `enrich_amundsen_ctd` for CTD variables linked by CTD filename.

The `ecotaxa_navigation` MCP prompt gives supporting agents detailed rules
about data grain, taxonomy, ambiguity, objects, and persistence. The main
tools also contain the most important guidance for clients that do not load
MCP prompts automatically.

One row in `samples_cache` represents one EcoTaxa sample. `project_id` is its
parent project, `profile_id` is a profile/cast, and `station_id` is a station.
Missing dates, depths, and coordinates are unknown and must not be treated as
negative values. IHO physical zones and MEOW ecoregions must remain separate.

`read_query` accepts one read-only `SELECT` or CTE and returns at most 500
rows. Use `LIMIT` and `OFFSET` to page larger requests.

## TSV Results

After a useful query, the agent should offer TSV conversion only when you want
to keep, download, share, or reuse the selection. `export_query_tsv` returns
`{filename, tsv}` to the host agent. The host agent saves the content in its
own workspace; the MCP server does not create or keep a file.

## External Enrichments

Every enrichment begins with a plan without a network request. The agent shows
that plan and proceeds with `confirmed=true` only after you agree.

### EcoPart

`enrich_ecopart` accepts the contents of an already exported EcoTaxa **object
TSV**, never cache SQL or a sample TSV. It requires an object ID, `project_id`,
a profile/sample identifier, and object depth. It retrieves the linked EcoPart
profiles, joins each object by profile and 5 m depth bin, and returns
`ecotaxa_ecopart_enriched.tsv` to the host agent. It requires EcoPart access:
add `ECOPART_TOKEN`, or `ECOTAXA_USERNAME` and `ECOTAXA_PASSWORD`, to `.env`.

### Amundsen CTD

`enrich_amundsen_ctd` requires `ctd_rosette_filename`. The filename identifies
the profile in Amundsen ERDDAP; station, time, and position make the match
auditable, and the measurement at the nearest source depth in `PRES` is used.
No account is required.

The MCP keeps no external-enrichment result in its cache or container.
Amundsen returns structured rows; EcoPart returns an enriched TSV and a
preview. The host agent keeps the result in its DataFrame, session, or a file
only when you ask it to.

## Updating the Cache (Maintainers Only)

To create a new cache release, set `ECOTAXA_CACHE_MODE=publisher`, provide
EcoTaxa credentials, and provide a `GITHUB_TOKEN` with write access to this
repository. After a complete successful synchronization, the server replaces
the assets of the `ecotaxa-cache-current` release.

Add these private values to the maintainer's `.env`:

```dotenv
ECOTAXA_CACHE_MODE=publisher
ECOTAXA_TOKEN=your-ecotaxa-token
GITHUB_TOKEN=your-github-token
```

Use `ECOTAXA_USERNAME` and `ECOTAXA_PASSWORD` instead of `ECOTAXA_TOKEN` only
when token authentication is unavailable. Advanced synchronization settings
remain optional: `ECOTAXA_NIGHTLY_SYNC`, `ECOTAXA_SYNC_HOUR`,
`ECOTAXA_CACHE_MAX_AGE_HOURS`, and `ECOTAXA_CACHE_AUTO_PUBLISH`.

## Quick Check

```bash
curl http://localhost:8001/health
```

A `200` response confirms the server is reachable. When the cache is ready,
ask, for example: “List samples in Baffin Bay” or “Which UVP6 projects are
available?”.

## Development

```bash
python -m pip install -r requirements-dev.txt
pytest -q tests/test_mcp_tool_surface.py tests/test_mcp_health.py tests/test_mcp_scheduler.py
```

EcoTaxa credentials and MCP tokens must remain exclusively in `.env`.