# mcp-apollo-config

MCP server for Apollo Config Center using **portal username/password login**, implemented with **FastMCP**.

## Install

```bash
pip install mcp-apollo-config
```

Local editable install:

```bash
pip install -e .
```

## Auth Mode

The plugin authenticates by portal session:

1. `POST /signin` with username/password
2. Receives login session cookie (`SESSION` or `JSESSIONID`)
3. Uses portal management APIs under `/apps/{appId}/envs/{env}/...`

No OpenAPI token is required.

## Governance Mode

- `readonly` (default): query only
- `editable`: query + edit (requires `--operator`)

## MCP Configuration

Configure the server in your MCP client with `command` + `args`:

```json
{
  "mcpServers": {
    "apollo": {
      "command": "mcp-apollo-config",
      "args": [
        "--portal-url", "http://apollo-portal.example.com",
        "--username", "your.username",
        "--password", "your.password",
        "--governance-mode", "readonly",
        "--default-app-id", "your-app-id",
        "--default-env", "DEV",
        "--default-cluster", "default",
        "--default-namespace", "application"
      ]
    }
  }
}
```

## Full Parameters

Required:

- `--portal-url` or `APOLLO_PORTAL_URL`
- `--username` or `APOLLO_USERNAME`
- `--password` or `APOLLO_PASSWORD`

Optional:

- `--login-submit` or `APOLLO_LOGIN_SUBMIT`
- `--governance-mode` or `APOLLO_GOVERNANCE_MODE`: `readonly|editable`
- `--operator` or `APOLLO_OPERATOR` (required in editable mode)
- `--default-app-id` or `APOLLO_DEFAULT_APP_ID`
- `--default-env` or `APOLLO_DEFAULT_ENV` (for example `DEV`, `TEST`)
- `--default-cluster` or `APOLLO_DEFAULT_CLUSTER` (default: `default`)
- `--default-namespace` or `APOLLO_DEFAULT_NAMESPACE`
- `--timeout-ms` or `APOLLO_TIMEOUT_MS` (default: `10000`)
- `--log-level` or `MCP_APOLLO_LOG_LEVEL`: `DEBUG|INFO|WARN|ERROR` (default: `WARN`)
- `--debug-http` or `MCP_APOLLO_DEBUG_HTTP=true`

## Tools

- `apollo_get_namespace_configs`: query all key/value items under a namespace/environment/cluster with pagination controls (`pageSize`, `maxItems`).
- `apollo_get_key`: query one config key under a namespace/environment/cluster.
- `apollo_edit_key` (editable mode only): create or update one key and return the updated item.

## Tests

Local tests use a **mock Apollo portal server** and do not require real credentials or network access.

```bash
python -m unittest discover -s tests -p "test_*.py"
```

Covered scenarios:

- `tools/list` in readonly and editable mode
- `apollo_get_key`
- `apollo_get_namespace_configs`
- `apollo_edit_key`
- Portal session login + cookie flow

## Notes

- The management API path includes `/envs/{env}`. Set `--default-env` or pass `env` in tool arguments.
- The server is built on FastMCP and runs in stdio transport mode.
- After editing a key, Apollo release may still be needed before clients see the change.
- Avoid keeping `DEBUG` logs enabled in production for long periods.

## Chinese README

- [README.zh-CN.md](/E:/workspace/mcp-apollo/README.zh-CN.md)