# ALA API MCP Server

[![CI](https://github.com/yourusername/ala-mcp/workflows/CI/badge.svg)](https://github.com/yourusername/ala-mcp/actions)
[![codecov](https://codecov.io/gh/yourusername/ala-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/yourusername/ala-mcp)
[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Model Context Protocol (MCP) server for interacting with the [Atlas of Living Australia (ALA)](https://www.ala.org.au/) API.

Disclaimer: This is a vibe-coded project and only intended for demonstration and educational purposes for the internal ALA team.

## Quick Start

### Installation

```bash
# Clone the repository
git clone https://github.com/yourusername/ala-mcp.git
cd ala-mcp

# Install in development mode with all dependencies
make install-dev

# Or use pip directly
pip install -e ".[dev]"
```

### Running the Server

```bash
# Run directly
python -m ala_mcp

# Or use the convenience script
./server.py

# Or use make
make run
```

### Configuration with MCP Clients

#### Amazon Q

```bash
q mcp add --name ala-api \
  --command /path/to/venv/bin/python \
  --args /path/to/ala-mcp/src/ala_mcp/__main__.py
```

#### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "ala-api": {
      "command": "/absolute/path/to/ala-mcp/venv/bin/python",
      "args": ["-m", "ala_mcp"],
      "env": {}
    }
  }
}
```

**Important:**
- Use the **absolute path** to your venv's Python (e.g., `/Users/username/Projects/ala-mcp/venv/bin/python`)
- The `-m ala_mcp` argument runs the package as a module
- Do NOT use just `python` - it won't be found in Claude Desktop's PATH

## Usage

The server exposes **7 MCP tools** for interacting with the Atlas of Living Australia API:

1. **search_occurrences** - Search 152+ million biodiversity records with filtering and spatial search
2. **get_occurrence** - Get detailed information about a specific occurrence by UUID
3. **download_occurrences** - Request bulk data downloads (sent via email)
4. **count_taxa** - Get occurrence counts for taxa lists
5. **create_query_id** - Create cached query IDs for complex searches
6. **get_query** - Retrieve stored query parameters
7. **api_request** - Advanced: Direct API access for custom requests

For a complete list of available endpoints and examples, see [API_ENDPOINTS.md](API_ENDPOINTS.md).

### Example Requests

**Search for occurrences using search_occurrences tool:**

MCP clients will see this tool with parameters:
- `query` (required): Search term (e.g., "Eucalyptus", "*:*")
- `filters` (optional): Array of filter queries
- `pageSize` (optional): Results per page (default: 10)
- `lat`, `lon`, `radius` (optional): Spatial search
- `facets` (optional): Facet fields for aggregation

**Get specific occurrence using get_occurrence tool:**

Simply provide the UUID:
- `uuid` (required): The occurrence record identifier

**Download data using download_occurrences tool:**

Parameters:
- `query` (required): Search query
- `email` (required): Email for download notification
- `reasonTypeId` (required): Download reason code (e.g., "10" for testing)
- `fields` (required): Comma-separated field list
- `filters` (optional): Filter queries
- `fileType` (optional): "csv" or "tsv" (default: csv)

**Advanced users can use api_request tool:**

For direct API access with custom parameters:
- `method`: GET, POST, PUT, DELETE
- `endpoint`: API path
- `params`: Query parameters
- `data`: Request body
- `headers`: Custom headers

See [API_ENDPOINTS.md](API_ENDPOINTS.md) for comprehensive endpoint documentation and more examples.

## Configuration

The server can be configured using environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `ALA_BASE_URL` | `https://biocache-ws.ala.org.au/ws` | ALA API base URL |
| `ALA_DEFAULT_TIMEOUT` | `30` | Request timeout in seconds |
| `ALA_LOG_LEVEL` | `INFO` | Logging level |
| `ALA_API_KEY` | `None` | Optional API key for authentication |

### Using .env file

Create a `.env` file in the project root:

```bash
ALA_BASE_URL=https://biocache-ws.ala.org.au/ws
ALA_LOG_LEVEL=DEBUG
ALA_API_KEY=your-api-key-here
```

## Development

### Setup Development Environment

```bash
# Install development dependencies
make install-dev

# Install pre-commit hooks
make pre-commit
```

### Running Tests

```bash
# Run all tests
make test

# Run with coverage report
make test-cov

# Run specific test file
pytest tests/test_client.py
```

### Code Quality

```bash
# Format code
make format

# Run linting
make lint

# Run type checking
make type-check

# Run security checks
make security

# Run everything
make all
```

### Available Make Commands

Run `make help` to see all available commands:

- `make install` - Install production dependencies
- `make install-dev` - Install development dependencies
- `make test` - Run tests
- `make test-cov` - Run tests with coverage
- `make lint` - Run linting
- `make format` - Format code
- `make type-check` - Run type checking
- `make security` - Run security checks
- `make clean` - Clean build artifacts
- `make run` - Run the server
- `make build` - Build distribution packages

## Project Structure

```
ala-mcp/
├── .github/
│   └── workflows/          # CI/CD workflows
├── src/
│   └── ala_mcp/
│       ├── __init__.py     # Package initialization
│       ├── __main__.py     # Entry point
│       ├── server.py       # MCP server implementation
│       ├── client.py       # ALA API client
│       ├── config.py       # Configuration management
│       └── logging_config.py # Logging setup
├── tests/                  # Test suite
│   ├── conftest.py        # Test fixtures
│   ├── test_server.py     # Server tests
│   ├── test_client.py     # Client tests
│   └── test_config.py     # Config tests
├── pyproject.toml         # Project metadata and dependencies
├── Makefile               # Development commands
└── README.md              # This file
```

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on:

- Code of Conduct
- Development workflow
- Submitting pull requests
- Coding standards

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Troubleshooting

### Server fails to start

1. Ensure dependencies are installed: `pip install -e ".[dev]"`
2. Check Python version: `python --version` (requires 3.10+)
3. Verify virtual environment is activated

### Tests failing

1. Install test dependencies: `pip install -e ".[dev]"`
2. Clear cache: `make clean`
3. Check for import errors: `python -c "import ala_mcp"`

### MCP client connection issues

1. Verify server path in configuration
2. Check server logs for errors
3. Test server manually: `python -m ala_mcp`

## Resources

- [Atlas of Living Australia API Documentation](https://api.ala.org.au/)
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [Project Issues](https://github.com/yourusername/ala-mcp/issues)

## Acknowledgments

- Atlas of Living Australia for providing the biodiversity data API
- The MCP community for the protocol specification
- All contributors to this project