Metadata-Version: 2.3
Name: axmp-openapi-fastmcp-server
Version: 1.3.0rc3
Summary: Add your description here
Author: Kilsoo Kang
Author-email: Kilsoo Kang <kilsoo75@gmail.com>
Requires-Dist: anyio>=4.0
Requires-Dist: diskcache>=5.6.3
Requires-Dist: fastmcp==4.0.3
Requires-Dist: httpx2>=2.12.0,<2.13
Requires-Dist: markdownify>=1.2.3
Requires-Dist: pathvalidate>=3.3.1
Requires-Dist: py-key-value-aio[redis]>=0.4.4
Requires-Dist: pydantic>=2.12.5
Requires-Dist: pydantic-settings>=2.12.0
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: starlette>=1.3.1
Requires-Dist: uvicorn>=0.30
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# AXMP OpenAPI FastMCP Server

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![FastMCP](https://img.shields.io/badge/FastMCP-3.0.0b1+-green.svg)](https://github.com/jlowin/fastmcp)
[![License](https://img.shields.io/badge/license-MIT-lightgrey.svg)](LICENSE)

> **Multiple OpenAPI backends to a single MCP server** — Profile-based configuration with multi-provider OAuth support.

AXMP OpenAPI FastMCP Server는 여러 OpenAPI 호환 백엔드 서비스를 하나의 통합 MCP(Model Context Protocol) 서버로 노출하는 래퍼입니다. [FastMCP](https://github.com/jlowin/fastmcp) 프레임워크를 기반으로 OpenAPI 스펙의 각 operation을 MCP Tool로 자동 변환하며, Keycloak/Google/GitHub/Azure OAuth 인증을 지원합니다.

---

## Table of Contents

- [Architecture](#architecture)
- [Features](#features)
- [Project Structure](#project-structure)
- [Installation](#installation)
- [Configuration](#configuration)
  - [Environment Variables](#environment-variables)
  - [MCP Profile](#mcp-profile)
  - [Backend Auth Config](#backend-auth-config)
- [Usage](#usage)
  - [CLI Mode (HTTP)](#cli-mode-http)
  - [CLI Mode (stdio)](#cli-mode-stdio)
  - [Container Mode](#container-mode)
  - [Health Check](#health-check)
  - [MCP Host Configuration](#mcp-host-configuration)
- [Authentication](#authentication)
  - [위임 scope](#위임-scope)
- [Tool Configuration](#tool-configuration)
- [Docker](#docker)
- [Development](#development)
- [CI/CD](#cicd)

---

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                        MCP Host                                 │
│              (Claude Desktop, Cursor, etc.)                     │
└──────────────────────┬──────────────────────────────────────────┘
                       │  MCP Protocol (stdio / HTTP)
                       ▼
┌─────────────────────────────────────────────────────────────────┐
│               AXMP OpenAPI FastMCP Server                       │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  OAuth Provider (Keycloak / Google / GitHub / Azure)      │  │
│  └───────────────────────────────────────────────────────────┘  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐            │
│  │  OpenAPI     │  │  OpenAPI     │  │  OpenAPI     │  ...      │
│  │  Provider A  │  │  Provider B  │  │  Provider C  │           │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘            │
│         │                │                │                     │
│  ┌──────┴──────┐  ┌──────┴──────┐  ┌──────┴──────┐            │
│  │ httpx2 Clnt │  │ httpx2 Clnt │  │ httpx2 Clnt │             │
│  │ (API Key)   │  │ (Bearer)    │  │ (Basic)     │             │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘            │
└─────────┼────────────────┼────────────────┼─────────────────────┘
          ▼                ▼                ▼
   ┌──────────┐     ┌──────────┐     ┌──────────┐
   │ Backend  │     │ Backend  │     │ Backend  │
   │ Server A │     │ Server B │     │ Server C │
   └──────────┘     └──────────┘     └──────────┘
```

---

## Features

- **Multi-Backend 통합** — 여러 OpenAPI 백엔드를 하나의 MCP 서버로 통합
- **Profile 기반 설정** — JSON 프로필로 백엔드 구성을 관리
- **Multi-Provider OAuth** — Keycloak, Google, GitHub, Azure 지원
- **Token Forwarding** — 업스트림 OAuth 토큰을 백엔드에 자동 전달
- **유연한 인증** — None / Basic / BearerToken / ApiKey 백엔드별 개별 인증
- **Tool Filtering** — `api_maps`에 명시한 경로와 메서드만 Tool로 노출
- **Custom Tool Naming** — 기본 `operationId` 대신 사용자 정의 Tool 이름 지정
- **Tool Description Override** — Tool 설명을 프로필에서 직접 재정의
- **Tool Output 전처리** — Tool별 응답 필드 include/exclude 및 필드 변환(HTML → Markdown)
- **위임 scope** — 승인 화면에서 사용자가 체크한 scope만 MCP 클라이언트 토큰에 싣고, 맡기지 않은 scope가 필요한 Tool은 목록에서 숨기고 호출을 거부
- **Dual Transport** — `stdio` (로컬) / `http` (원격) 전송 모드
- **Dual Entry Point** — CLI (인자 기반) / Container (환경변수 기반)
- **Multi-Arch Docker** — `linux/amd64`, `linux/arm64` 지원

---

## Project Structure

```
axmp-openapi-fastmcp-server/
├── src/axmp_openapi_fastmcp_server/
│   ├── __init__.py                      # Logging configuration
│   ├── __main__.py                      # python -m entry point
│   ├── settings.py                      # Pydantic Settings (MCP + OAuth)
│   ├── types.py                         # Enums (TransportType, OAuthProvider, AuthHeaderKey)
│   ├── multi_openapi_spec.py            # Multi-backend configuration models
│   ├── openapi_fastmcp_server.py        # Core wrapper (FastMCP + OpenAPI providers)
│   ├── runner/
│   │   ├── cli.py                       # CLI entry point (Click)
│   │   └── container.py                 # Container entry point (env-based)
│   └── auth/
│       ├── consent_page.py              # 위임 scope 승인 화면 (체크박스)
│       ├── delegated_scope.py           # 위임 scope (토큰 scope)
│       └── providers/
│           └── keycloak.py              # Keycloak OAuth provider
├── mcp_profiles/                        # MCP profile & OpenAPI spec files
│   ├── mcp_profile_<id>.json            # Backend configuration profiles
│   ├── mcp_profile_v2_<id>.json         # Profiles that define scopes
│   └── backend_server_<id>.json         # OpenAPI spec files
├── .env                                 # Environment variables
├── Dockerfile                           # Container image definition
├── pyproject.toml                       # Project metadata & dependencies
├── .github/workflows/
│   ├── cicd-for-tag.yml                 # CI/CD pipeline (Docker build & push)
│   └── publish.yml                      # PyPI publish & GitHub Release
└── .pre-commit-config.yaml              # Pre-commit hooks (ruff)
```

---

## Installation

### Requirements

- Python >= 3.12
- [uv](https://docs.astral.sh/uv/) (recommended package manager)

### Install from source

```bash
# Clone repository
git clone <repository-url>
cd axmp-openapi-fastmcp-server

# Install dependencies
uv sync

# Or with pip
pip install -e .
```

### Install from package

```bash
pip install axmp-openapi-fastmcp-server
```

---

## Configuration

### Environment Variables

`.env` 파일 또는 시스템 환경변수로 설정합니다.

#### MCP Server Settings (`AXMP_MCP_` prefix)

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `AXMP_MCP_SERVER_NAME` | MCP 서버 이름. Redis를 쓰고 `AXMP_MCP_REDIS_KEY_PREFIX`를 주지 않으면 키 prefix에 들어가므로, 배포 뒤에 바꾸면 연결된 클라이언트가 다시 등록하고 로그인해야 한다 | - | Yes |
| `AXMP_MCP_DISPLAY_NAME` | 승인 화면과 MCP 연결 응답의 `serverInfo.name`에 보이는 서버 이름. 미설정이거나 비어 있으면 `AXMP_MCP_SERVER_NAME`을 쓴다. Redis 키에는 쓰지 않으므로 바꿔도 연결된 클라이언트에 영향이 없다 | - | No |
| `AXMP_MCP_PORT` | HTTP 리스닝 포트 | `21000` | No |
| `AXMP_MCP_TRANSPORT_TYPE` | 전송 방식 (`http` / `stdio`) | `http` | No |
| `AXMP_MCP_PROFILE_BASE_PATH` | MCP 프로필 디렉토리 경로 | - | Yes |
| `AXMP_MCP_PROFILE_ID` | 사용할 프로필 ID | - | Yes |
| `AXMP_MCP_USE_AUTHORIZATION` | OAuth 인증 활성화 | `False` | No |
| `AXMP_MCP_FORWARD_TOKEN_TO_BACKEND` | 업스트림 토큰을 백엔드에 전달 | `False` | No |
| `AXMP_MCP_PATH_PREFIX` | AI Gateway subpath 노출용 path 한 단계 (예: `weather`). 설정 시 MCP와 OAuth 엔드포인트가 `/weather/mcp`, `/weather/authorize` 등 path 아래에서 서빙되고, well-known 메타데이터는 `/.well-known/oauth-authorization-server/weather`처럼 path가 뒤에 붙는다. `/healthz`는 루트 유지. 게이트웨이가 prefix를 떼지 않고 그대로 전달한다는 전제. 소문자·숫자·하이픈만 허용, 미설정 시 루트 | - | No |
| `AXMP_MCP_REDIS_URL` | Redis 접속 URL. 설정 시 OAuth 스토리지가 Redis로 전환됨 (미설정 시 디스크). 형식: `redis://[user[:password]@]host[:port][/db]` 또는 TLS는 `rediss://...` | - | No |
| `AXMP_MCP_REDIS_KEY_PREFIX` | Redis 키 격리 prefix | `axmp-mcp:{SERVER_NAME}` | No |
| `AXMP_MCP_REDIS_CLIENT_TTL_DAYS` | DCR 클라이언트 등록 sliding TTL (일). 미사용 클라이언트 자동 청소 기간 | `14` | No |
| `AXMP_MCP_LOG_LEVEL` | 로그 레벨. `DEBUG`는 API 키와 자격 증명 헤더 값을 평문으로 출력하므로 로컬 디버깅에만 쓴다 | `INFO` | No |

> Redis 모드는 `AXMP_MCP_REDIS_URL` 존재 여부만으로 활성화됩니다. 서버 시작 시 ping으로 연결을 검증하며, 실패 시 서버가 시작되지 않습니다 (silent fallback 없음). URL에 password가 포함될 수 있어 내부적으로 `SecretStr`로 다루며, 로그에는 host:port만 노출됩니다.

#### OAuth Settings (`AXMP_OAUTH_` prefix)

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `AXMP_OAUTH_PROVIDER` | OAuth 제공자 (`keycloak` / `okta` / `google` / `github` / `azure`) | `keycloak` | No |
| `AXMP_OAUTH_ISSUER_URL` | OAuth Issuer URL (Keycloak realm URL 등) | - | Yes* |
| `AXMP_OAUTH_CLIENT_ID` | OAuth Client ID | - | Yes* |
| `AXMP_OAUTH_CLIENT_SECRET` | OAuth Client Secret | - | Yes* |
| `AXMP_OAUTH_BASE_URL` | MCP 서버 base URL (callback용). `AXMP_MCP_PATH_PREFIX`가 있어도 path 없이 `https://<host>`로 주며, 서버가 prefix를 붙여 공개 URL을 만든다 | - | Yes* |
| `AXMP_OAUTH_REQUIRED_SCOPES` | 필요 OAuth 스코프 (JSON 배열 문자열, 예: `'["openid","profile","email","offline_access"]'`). `offline_access` 는 업스트림 IdP 에서 refresh_token 을 받기 위해 필요. Google 은 refresh_token 을 `access_type=offline` 으로 받고 토큰에 `offline_access` 가 없어 `keycloak`/`okta` 에만 기본으로 넣음 | `keycloak`/`okta`: `["openid","profile","email","offline_access"]`, 그 외: `["openid","profile","email"]` | No |
| `AXMP_OAUTH_REQUIRE_AUTHORIZATION_CONSENT` | 클라이언트가 연결할 때마다 승인 화면을 띄운다. 프로필에 `scopes`가 있으면 `True`여야 서버가 시작한다 | `False` | No |
| `AXMP_OAUTH_STORAGE_PATH` | 토큰 저장 경로 | `~/.fastmcp/server/oauth-proxy` | No |
| `AXMP_OAUTH_FALLBACK_REFRESH_TOKEN_EXPIRY_SECONDS` | upstream이 `refresh_expires_in`을 주지 않거나 `0`으로 줄 때(Okta, Keycloak offline 토큰) 자체 발급 refresh 토큰 수명(초). upstream이 값을 주면 그 값을 따름 | `43200` (12시간) | No |
| `AXMP_OAUTH_FALLBACK_ACCESS_TOKEN_EXPIRY_SECONDS` | upstream이 `expires_in`을 주지 않을 때 자체 발급 access 토큰 수명(초). Okta/Keycloak은 항상 `expires_in`을 주므로 보통 발동하지 않음. `keycloak`/`okta` provider에만 적용 (FastMCP 내장 Google/GitHub/Azure는 미지원) | `3600` (1시간) | No |
| `AXMP_OAUTH_TOKEN_EXPIRY_THRESHOLD_SECONDS` | upstream 토큰 만료 N초 전에 선제 refresh. `0`이면 만료 후 검증 실패 시에만 refresh | `30` | No |

> \* `AXMP_MCP_USE_AUTHORIZATION=True`인 경우 필수

> 토큰 수명 설정은 FastMCP `OAuthProxy`가 클라이언트에 발급하는 자체 JWT와 저장소 TTL에만 적용됩니다. 실제 갱신 가능 여부는 upstream IdP 정책이 결정하며, Okta 정책이 설정값보다 짧으면 refresh가 `invalid_grant`로 실패해 재인증으로 떨어집니다. Keycloak은 보통 `refresh_expires_in`을 응답에 포함해 refresh fallback이 적용되지 않지만, `offline_access` 스코프로 받은 offline 토큰은 `refresh_expires_in: 0`으로 내려오며 FastMCP가 이를 미제공으로 취급하므로 fallback 값이 적용됩니다. `AXMP_OAUTH_TOKEN_EXPIRY_THRESHOLD_SECONDS`는 upstream access 토큰 수명보다 충분히 작게(예: 30~60) 설정해야 합니다. 수명 이상으로 설정하면 매 요청마다 upstream refresh가 발생합니다.

#### Example `.env`

```bash
# MCP Server
AXMP_MCP_SERVER_NAME="axmp-openapi-fastmcp-server"
AXMP_MCP_PORT=8000
AXMP_MCP_TRANSPORT_TYPE="http"
AXMP_MCP_USE_AUTHORIZATION="True"
AXMP_MCP_FORWARD_TOKEN_TO_BACKEND="True"
AXMP_MCP_PROFILE_BASE_PATH="/path/to/mcp_profiles"
AXMP_MCP_PROFILE_ID="1234567890"

# OAuth (Keycloak)
AXMP_OAUTH_PROVIDER="keycloak"
AXMP_OAUTH_ISSUER_URL="https://keycloak.example.com/auth/realms/your-realm"
AXMP_OAUTH_CLIENT_ID="studio-client"
AXMP_OAUTH_CLIENT_SECRET="your-client-secret"
AXMP_OAUTH_BASE_URL="http://127.0.0.1:8000"
AXMP_OAUTH_STORAGE_PATH="/path/to/.fastmcp/server/oauth-proxy"

# Redis OAuth storage (optional — enables shared storage across instances)
# AXMP_MCP_REDIS_URL="redis://:redis-password@redis.example.com:6379/0"
```

### MCP Profile

MCP 프로필은 백엔드 서버 구성을 정의하는 JSON 파일입니다. 파일 이름은 `mcp_profile_<profile-id>.json` 형식을 따릅니다.

[위임 scope](#위임-scope)를 정의한 프로필은 core가 `mcp_profile_v2_<profile-id>.json` 이름으로 넘긴다. 서버는 이 이름을 먼저 찾고, 없으면 `mcp_profile_<profile-id>.json`을 읽는다. scope를 모르는 옛 런타임은 새 이름을 찾지 못해 시작하지 않으므로, scope 검사 없이 모든 Tool이 열리는 일이 없다.

```json
{
  "backends": [
    {
      "server_name": "studio-backend",
      "endpoint": "https://api.example.com",
      "base_path": "/",
      "timeout": 10,
      "tls_verify": true,
      "spec_file_path": "studio-api.json",
      "auth_config": {
        "type": "ApiKey",
        "api_key_name": "X-Access-Key",
        "api_key_value": "your-api-key"
      },
      "tool_config": {
        "api_maps": [
          {
            "path": "/api/v1/agents",
            "methods": ["get", "post"]
          },
          {
            "path": "/api/v1/agents/{agent_id}",
            "methods": [
              {
                "method": "get",
                "tool_name": "get_agent_by_id",
                "description": "Get agent details by ID"
              }
            ]
          }
        ]
      }
    }
  ]
}
```

#### Backend Configuration Fields

| Field | Type | Description | Required |
|-------|------|-------------|----------|
| `server_name` | `string` | 백엔드 식별 이름 | Yes |
| `endpoint` | `string` | 백엔드 서버 URL | Yes |
| `base_path` | `string` | spec 의 `servers` URL 이 가진 path. 요청 URL 은 `endpoint + base_path + spec path` 로 만들어진다. spec 의 path 가 이미 이 prefix 를 포함하면 붙이지 않는다 | No (`/`) |
| `timeout` | `float` | 요청 타임아웃 (초) | No (`10`) |
| `tls_verify` | `bool` | TLS 인증서 검증 | No (`true`) |
| `spec_file_path` | `string` | OpenAPI spec JSON 파일 (프로필 디렉토리 기준 상대경로) | Yes |
| `auth_config` | `object` | 백엔드 인증 설정 | Yes |
| `tool_config` | `object` | Tool 필터링 및 커스터마이징 설정 | Yes |

### Backend Auth Config

| Auth Type | Fields | Description |
|-----------|--------|-------------|
| `None` | - | 인증 없음 |
| `Basic` | `username`, `password` | HTTP Basic 인증 |
| `BearerToken` | `bearer_token` | Bearer 토큰 인증 |
| `ApiKey` | `api_key_name`, `api_key_value` | 커스텀 헤더 API 키 |

---

## Usage

### CLI Mode (HTTP)

```bash
axmp-openapi-fastmcp-server \
  --port 21000 \
  --transport http \
  --server-name axmp-mixed-openapi-mcp-server \
  --profile-base-path /path/to/mcp_profiles \
  --profile-id 1234567890 \
  --backend-server-auth-configs "studio-backend:X-Access-Key=your-api-key,workspace-backend:X-Access-Key=your-api-key"
```

### CLI Mode (stdio)

```bash
axmp-openapi-fastmcp-server \
  --transport stdio \
  --profile-base-path /path/to/mcp_profiles \
  --profile-id 1234567890 \
  --backend-server-auth-configs "studio-backend:X-Access-Key=your-api-key"
```

#### CLI Options

| Option | Description | Default |
|--------|-------------|---------|
| `--transport` | 전송 방식 (`stdio` / `http` / `sse` / `streamable-http`) | `streamable-http` |
| `--port` | HTTP 리스닝 포트 | `21000` |
| `--server-name` | MCP 서버 이름 | `axmp-openapi-fastmcp-server-<profile-id>` |
| `--profile-base-path` | MCP 프로필 디렉토리 경로 | - (필수) |
| `--profile-id` | 프로필 ID | - (필수) |
| `--backend-server-auth-configs` | 런타임 인증 오버라이드 | - |

#### `--backend-server-auth-configs` Format

프로필의 auth 설정을 런타임에 오버라이드합니다:

```
<server-name>:<key-name>=<value>,<server-name>:<key-name>=<value>
```

- **ApiKey**: `studio-backend:X-Access-Key=zmp-xxxxx`
- **BearerToken**: `studio-backend:bearer_token=eyJhbGci...`
- **Basic**: `studio-backend:username=admin,studio-backend:password=secret`

### Container Mode

환경변수 기반으로 실행됩니다. `.env` 파일 또는 시스템 환경변수를 설정한 후:

```bash
uv run axmp-container-fastmcp-server
```

### Health Check

HTTP transport로 띄우면 `GET /healthz`가 200과 `{"result": "success"}`를 반환한다. OAuth를 켠 서버에서도 토큰 없이 호출할 수 있어서 Kubernetes probe나 모니터링에 쓸 수 있다. 백엔드와 Redis 상태는 확인하지 않으며, stdio transport에는 이 경로가 없다.

```bash
curl http://127.0.0.1:21000/healthz
```

### MCP Host Configuration

#### Claude Desktop / Cursor

`claude_desktop_config.json` 또는 MCP 호스트 설정에 추가:

```json
{
  "mcpServers": {
    "axmp-openapi-fastmcp-server": {
      "command": "python3",
      "args": [
        "-m",
        "axmp_openapi_fastmcp_server",
        "--transport", "stdio",
        "--profile-base-path", "/path/to/mcp_profiles",
        "--profile-id", "1234567890",
        "--backend-server-auth-configs",
        "studio-backend:X-Access-Key=your-api-key"
      ]
    }
  }
}
```

---

## Authentication

### OAuth Flow (HTTP transport)

`AXMP_MCP_USE_AUTHORIZATION=True`이고 transport가 `http`인 경우 OAuth 인증이 활성화됩니다.

```
MCP Client → MCP Server → OAuth Provider (Keycloak/Google/GitHub/Azure)
                │
                ├─ Token Introspection (검증)
                ├─ User Info Extraction (사용자 정보)
                └─ Scope Validation (스코프 확인)
```

### Token Forwarding

`AXMP_MCP_FORWARD_TOKEN_TO_BACKEND=True`이고 백엔드 auth type이 `BearerToken`인 경우, 업스트림 OAuth 토큰이 자동으로 백엔드 요청에 주입됩니다.

### 위임 scope

OAuth를 쓰는 서버에서, 사용자는 MCP 클라이언트를 연결할 때 승인 화면에서 그 클라이언트에 맡길 scope를 체크박스로 고른다. 체크한 scope는 이 서버가 클라이언트에 발급하는 토큰(JWT)의 `scope` claim에 실린다. IdP에는 authorize, 코드 교환, refresh 모두 `AXMP_OAUTH_REQUIRED_SCOPES`만 요청하므로 IdP에 scope를 따로 만들 필요가 없다.

프로필 최상위 `scopes`에 scope를 정의하고, `api_maps`의 객체 메서드마다 필요한 scope를 하나 지정한다. 예는 다음과 같다.

```json
{
  "scopes": [
    { "name": "menu:read", "description": "메뉴를 조회한다" },
    { "name": "order:cancel", "description": "주문을 취소한다" }
  ],
  "backends": [
    {
      "server_name": "hymeal-api",
      "tool_config": {
        "api_maps": [
          { "path": "/api/v1/menus", "methods": [{ "method": "get", "tool_name": "list_menus", "scope": "menu:read" }] },
          { "path": "/api/v1/orders/{orderId}", "methods": [{ "method": "delete", "tool_name": "cancel_order", "scope": "order:cancel" }] },
          { "path": "/api/v1/hours", "methods": ["get"] }
        ]
      }
    }
  ]
}
```

- 승인 화면은 scope마다 체크박스를 한 줄씩 그리고 처음에는 모두 해제해 둔다. 클라이언트가 무엇을 요청했든 정의한 scope를 모두 보이고, 펼치면 그 scope로 쓰는 Tool 이름이 나온다. 화면에는 스크립트가 없고 FastMCP 승인 화면과 같은 CSP를 쓴다.
- 맡기지 않은 scope가 필요한 Tool은 `tools/list`에서 빠지고, 호출하면 필요한 scope가 적힌 Tool 오류가 돌아온다. 이때 백엔드는 호출하지 않는다. scope를 지정하지 않은 Tool(문자열 메서드 포함)은 로그인한 클라이언트가 모두 쓴다.
- refresh 뒤에도 처음 고른 scope가 유지된다. 프로필에서 지운 scope는 지워져 있는 동안 요청 검사에서 빠지고, 그동안 refresh한 토큰에서는 없어진다. 그동안 refresh하지 않은 토큰은 같은 이름을 다시 정의하면 그 scope를 다시 쓴다. 그래서 scope의 뜻을 바꿀 때는 새 이름을 쓴다.
- 로그인 scope(`openid profile email` 등)로 이미 등록한 클라이언트도 막히지 않는다. 등록할 때 적은 scope 목록은 쓰지 않고 지금 정의한 목록으로 바꿔 보며, authorize에서 요청한 scope 가운데 모르는 것은 거절하지 않고 무시한다.
- 코드 교환 때 클라이언트 ID, IdP 사용자(`sub`), 고른 scope를 INFO 로그로 남긴다.
- OpenAPI 스펙 operation의 `axmp-scope:` 접두사 태그는 읽을 때 지운다. 이 접두사는 Tool의 scope 태그에 쓰인다.

다음 경우에는 서버가 시작하지 않는다.

- scope 이름이 `^[a-z0-9:._-]{1,64}$`에 맞지 않거나, 겹치거나, 설명이 비어 있다.
- Tool의 scope가 최상위 `scopes`에 없다. 빈 문자열도 정의되지 않은 scope로 본다. FastMCP는 규칙이 없는 태그를 통과시키므로, 그대로 두면 그 Tool이 모두에게 열린다.
- 한 백엔드의 `api_maps`에 같은 path와 method가 scope를 달리해 두 번 이상 나온다. 먼저 나온 항목만 Tool의 scope를 정하므로, 그대로 두면 뒤의 scope는 무시된다.
- scope 이름이 `openid`, `profile`, `email`, `offline_access`이거나 `AXMP_OAUTH_REQUIRED_SCOPES`에 있다.
- OAuth가 꺼져 있거나 transport가 `http`가 아니다. `AXMP_OAUTH_REQUIRE_AUTHORIZATION_CONSENT`가 `True`가 아니다.
- 설치된 FastMCP가 시험한 버전(4.0.3)이 아니다. 위임은 FastMCP 내부 메서드를 감싸므로 `pyproject.toml`에서 버전을 고정한다.

`scopes`가 없는 프로필은 FastMCP 기본 승인 화면을 쓰고, 로그인한 클라이언트가 모든 Tool을 쓴다.

scope가 없던 프로필에 scope를 정의해 다시 배포하면, 이미 연결한 클라이언트에는 새로 scope를 지정한 Tool이 보이지 않는다. 위임을 켜기 전에 발급된 토큰은 위임 scope를 하나도 갖지 않기 때문이다. IdP가 토큰에 위임 scope와 같은 이름의 scope를 넣어 주었더라도 마찬가지다. 서버는 위임을 켠 동안 발급한 토큰(`upstream_claims`의 `axmp_delegated` 표시)의 `scope` claim만 읽고, 표시가 없는 refresh token으로 갱신해도 위임 scope를 주지 않는다. 그 Tool을 쓰려면 다시 연결해 승인 화면에서 scope를 고른다.

scope를 정의했던 프로필에서 `scopes`를 모두 지우고 다시 배포하면, 위임을 켠 동안 등록한 클라이언트는 authorize에서 `invalid_scope`로 거절된다. 이 클라이언트들은 메타데이터가 알린 위임 scope 이름으로 등록했는데, 위임을 끈 서버는 등록할 때 적은 scope 밖의 요청을 받지 않기 때문이다. 이 클라이언트는 다시 등록해야 한다. Redis 저장소를 쓰면 이전 등록은 마지막으로 사용한 때부터 `AXMP_MCP_REDIS_CLIENT_TTL_DAYS`가 지나야 사라진다.

### Supported OAuth Providers

| Provider | Class | Description |
|----------|-------|-------------|
| `keycloak` | `KeyCloakProvider` | Custom implementation with token introspection |
| `google` | `GoogleProvider` | FastMCP built-in |
| `github` | `GitHubProvider` | FastMCP built-in |
| `azure` | `AzureProvider` | FastMCP built-in |

---

## Tool Configuration

### api_maps (Explicit)

특정 경로와 메서드를 명시적으로 MCP Tool로 등록합니다:

```json
{
  "api_maps": [
    {
      "path": "/api/v1/agents",
      "methods": ["get", "post"]
    },
    {
      "path": "/api/v1/agents/{agent_id}",
      "methods": [
        {
          "method": "get",
          "tool_name": "get_agent_detail",
          "description": "Get agent details"
        }
      ]
    }
  ]
}
```

- 문자열 메서드: OpenAPI `operationId`를 Tool 이름으로 사용
- 객체 메서드: `tool_name`과 `description` 커스터마이징 가능. `scope`로 이 Tool에 필요한 [위임 scope](#위임-scope)를 지정
- 명시되지 않은 경로는 항상 제외 (`MCPType.EXCLUDE`)
- `api_maps`가 비었거나 없는 백엔드는 Tool을 하나도 노출하지 않음 (기동 시 경고 로그 출력)

#### Tool Output 전처리 (output)

객체 메서드에 `output`을 지정하면 백엔드 응답(JSON)을 클라이언트에 전달하기 전에 가공합니다:

```json
{
  "method": "get",
  "tool_name": "get_articles",
  "output": {
    "include": ["items", "total"],
    "exclude": ["items.internal"],
    "transforms": [
      { "field": "items.body", "type": "html_to_markdown" }
    ]
  }
}
```

- `include`: 지정한 필드만 유지 (경로가 끝나는 지점의 하위 트리는 전체 유지)
- `exclude`: 지정한 필드 제거
- `transforms`: 문자열 필드 값을 변환. 지원 타입: `html_to_markdown`
- 적용 순서: `include` → `exclude` → `transforms`
- 필드 경로는 `.`으로 구분하며, 배열은 각 원소에 자동 적용 (`items.body` = `items[*].body`)
- 경로 기준은 Tool의 structured output입니다. 응답 최상위가 배열이면 FastMCP가 `result` 키로 감싸므로 `result.<field>` 형태로 지정
- `output`을 쓰려면 `tool_name`이 필수이며, `include`/`exclude`를 쓰는 Tool의 output schema는 Tool 목록에서 숨겨집니다
- `tool_name`은 FastMCP가 정규화(영숫자·`_`만 허용, 56자 제한)하므로, 등록된 Tool 이름과 다르면 설정이 적용되지 않고 경고 로그가 남습니다
- JSON이 아닌 응답(text 등)은 가공 없이 그대로 전달

### route_maps (미지원)

- 프로필 스키마에는 남아 있지만 서버가 읽지 않음
- `route_maps`만 지정한 백엔드는 Tool을 하나도 노출하지 않음
- `route_maps`가 비어 있지 않으면 기동 시 경고 로그 출력
- 노출할 API는 `api_maps`에 경로와 메서드로 지정

---

## Docker

### Build

```bash
docker build -t axmp-openapi-fastmcp-server .
```

### Run

```bash
docker run -d \
  --env-file .env \
  -p 8000:8000 \
  -v /path/to/mcp_profiles:/application/mcp_profiles \
  axmp-openapi-fastmcp-server
```

### Dockerfile Overview

```dockerfile
FROM python:3.12.10-slim
WORKDIR /application

# Virtual env + uv install
RUN python -m venv /application/.venv && \
    /application/.venv/bin/pip install uv

# Install dependencies (production only)
COPY . .
RUN /application/.venv/bin/uv sync --locked --no-cache --no-dev --compile-bytecode

# Container entry point (env-based)
CMD ["/application/.venv/bin/axmp-container-fastmcp-server"]
```

---

## Development

### Setup

```bash
# Install dev dependencies
uv sync

# Install pre-commit hooks
pre-commit install
```

### Linting & Formatting

```bash
# Lint
uv run ruff check .

# Format
uv run ruff format .
```

### Testing

```bash
# Run tests
uv run pytest

# Watch mode
uv run ptw
```

### Pre-commit Hooks

| Hook | Description |
|------|-------------|
| `trailing-whitespace` | 후행 공백 제거 |
| `end-of-file-fixer` | 파일 끝 개행 보장 |
| `debug-statements` | `pdb` import 감지 |
| `ruff` | Lint & auto-fix |
| `ruff-format` | 코드 포맷팅 |

---

## CI/CD

GitHub Actions를 통해 semantic versioning 태그(`v*.*.*`) 푸시 시 자동 빌드 & 배포됩니다.

### Pipeline

```
git tag v1.0.0 → push → GitHub Actions
                           ├─ Checkout
                           ├─ Setup QEMU (multi-arch)
                           ├─ Setup Docker Buildx
                           ├─ Login to Private Registry
                           ├─ Extract metadata (semver tags)
                           └─ Build & Push (linux/amd64, linux/arm64)
```

### Registry

- **Registry**: `zcr.cloudzcp.net`
- **Image**: `zcr.cloudzcp.net/cloudzcp/axmp-openapi-fastmcp-server`
- **Platforms**: `linux/amd64`, `linux/arm64`

### PyPI & GitHub Release

- `v*` 태그 푸시 시 `publish.yml`이 PyPI 배포와 GitHub Release 생성을 함께 수행
- rc, alpha, beta, dev 태그(`v1.2.0-rc1` 등)는 Pre-release로 생성되어 Latest 표시를 가져가지 않음
- 그 밖의 태그(`v1.2.0` 등)는 정식 릴리즈로 생성

---

## Tech Stack

| Category | Technology |
|----------|------------|
| Language | Python 3.12+ |
| MCP Framework | [FastMCP](https://github.com/jlowin/fastmcp) == 4.0.3 |
| Settings | Pydantic Settings |
| HTTP Client | httpx2 (async) |
| CLI | Click |
| OAuth | Keycloak / Google / GitHub / Azure |
| Encryption | Fernet (cryptography) |
| Build | uv |
| Linting | Ruff |
| Container | Docker (multi-arch) |
| CI/CD | GitHub Actions |

---

## Author

**Kilsoo Kang** — kilsoo75@gmail.com
