内容
# Polaris 目录 & Iceberg 管理 MCP 服务器
[FastMCP](https://github.com/jlowin/fastmcp) 服务器，为 AI 助手（和数据工程师）提供与 **Apache Polaris** 目录管理、**Iceberg REST Catalog** API 和 **PyIceberg** 表存储/健康检查工具的对话式访问。
它旨在使 AI 代理（如 Cursor、Windsurf 或 Claude Desktop）能够审计数据治理、检查访问控制角色、查询命名空间和检查 Iceberg 元数据。
---
## 功能
**12 种工具**，涵盖 10 个类别：
| 类别 | 工具名称 | 操作 | 您可以通过询问实现的功能 |
| --- | --- | --- | --- |
| **连接** | `connect` | 无 | "连接到 Polaris" |
| | `disconnect` | 无 | "断开与 Polaris 服务器的连接" |
| | `get_server_config` | 无 | "服务器支持哪些端点？" |
| **目录** | `catalog_request` | `list`，`get` | "存在哪些目录？", "显示目录 X 的存储配置" |
| **命名空间** | `namespace_request` | `list`，`get`，`exists` | "列出目录 X 中的所有命名空间", "命名空间 Y 是否存在？" |
| **表** | `table_request` | `list`，`get`，`exists` | "列出 prod.analytics 中的表", "显示表 Z 的模式和快照" |
| **视图** | `view_request` | `list`，`get`，`exists` | "列出视图", "加载 revenue_daily 视图元数据" |
| **主体** | `principal_request` | `list`，`get`，`roles_assigned` | "谁有访问权限？", "Alice 有哪些角色？" |
| **角色和授权** | `role_request` | `list_principal_roles`，`get_principal_role`，`list_principals_for_role`，`list_catalog_roles`，`get_catalog_role`，`list_catalog_roles_for_principal_role`，`list_principal_roles_for_catalog_role`，`list_grants_for_catalog_role` | "存在哪些角色？", "哪些目录角色映射到 service_admin？", "analyst 角色有哪些特权？" |
| **策略** | `policy_request` | `list`，`get`，`get_applicable` | "哪些策略适用于此表？", "显示压缩策略" |
| **通用表** | `generic_table_request` | `list`，`get` | "注册了哪些 Delta/CSV 表？" |
| **元数据检查** | `inspect_request` | `snapshots`，`files`，`manifests`，`partitions`，`health` | "检查快照历史", "列出原始 Parquet 数据/删除文件", "显示分区健康/删除文件开销" |
---
## 快速入门
### 安装
```bash
cd apache-polaris-iceberg-ai-mcp
pip install -e .
```
### 运行服务器
```bash
# 通过 FastMCP CLI
fastmcp run server.py
# 或直接运行
python -m server
```
### 在 Claude Desktop 中配置
添加到您的 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"polaris-catalog": {
"command": "fastmcp",
"args": ["run", "/path/to/apache-polaris-iceberg-ai-mcp/server.py"]
}
}
}
```
### 在 VS Code（Copilot / Cline / 等）中配置
添加到您的 `.vscode/mcp.json` 或 MCP 设置：
```json
{
"servers": {
"polaris-catalog": {
"command": "fastmcp",
"args": ["run", "/path/to/apache-polaris-iceberg-ai-mcp/server.py"]
}
}
}
```
---
## 身份验证
服务器通过 `connect` 工具支持三种身份验证模式：
### 1. 客户端凭证（默认）
```
connect(uri="http://localhost:8181", client_id="admin", client_secret="password")
```
### 2. Bearer Token
```
connect(uri="http://localhost:8181", token="eyJhbGciOiJSUzI1NiIs...")
```
### 3. Keycloak / OIDC 密码凭证
使用此方法先将用户名/密码凭证兑换为 Keycloak 或另一个 OIDC 提供者的令牌，然后使用该令牌身份验证到 Polaris：
```
connect(
uri="http://localhost:8181",
oauth_token_url="http://localhost:8080/realms/polaris-realm/protocol/openid-connect/token",
client_id="polaris-client",
client_secret="sBbUvTG7qWGbmgwgxKmnEuzqpuE3uGAu",
username="sankeerth",
password="nagapuri"
)
```
---
## 存储和检查配置
由于 `inspect_request` 工具直接从对象存储读取底层 Avro 元数据和 Parquet 数据/删除文件，因此您应该配置 S3/MinIO 环境变量或动态传递选项。
### S3 / MinIO 环境变量
默认情况下，检查工具查找这些环境变量或回退到本地 MinIO 开发默认值（`admin` / `password` / `http://localhost:9000`）：
* `S3_ENDPOINT`：S3 端点 URL（例如，`http://localhost:9000` 或 `https://s3.amazonaws.com`）
* `AWS_ACCESS_KEY_ID`：您的 AWS 或 MinIO 访问密钥
* `AWS_SECRET_ACCESS_KEY`：您的 AWS 或 MinIO 秘密密钥
### 重写参数
`inspect_request` 工具还接受可选的重写：
* `s3_endpoint`
* `aws_access_key_id`
* `aws_secret_access_key`
---
## 架构
```
apache-polaris-iceberg-ai-mcp/
├── server.py # FastMCP 服务器 — 注册综合工具
├── client.py # 异步 HTTP 客户端（httpx）带有 OAuth2 + 密码授权认证
├── requirements.txt # 依赖项（fastmcp, httpx, pydantic, pyiceberg, pyarrow, s3fs）
└── tools/ # 按域划分的工具实现
├── connection.py # connect, disconnect, get_server_config
├── catalogs.py # catalog_request (list, get)
├── principals.py # principal_request (list, get, roles_assigned)
├── roles.py # role_request (principal/catalog roles, mapping, grants)
├── namespaces.py # namespace_request (list, get, exists)
├── tables.py # table_request (list, get, exists)
├── views.py # view_request (list, get, exists)
├── policies.py # policy_request (list, get, get_applicable)
├── generic_tables.py # generic_table_request (list, get)
└── inspect.py # inspect_request (snapshots, files, manifests, partitions, health)
```
---
## 许可证
MIT 许可证
