# Archery MCP Server

[![PyPI](https://img.shields.io/pypi/v/archery-mcp-server)](https://pypi.org/project/archery-mcp-server/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

将 [Archery](https://github.com/hhyo/Archery) SQL 审核查询平台的 API 封装为 [MCP](https://modelcontextprotocol.io/) 工具，让 AI Agent（Kiro/Claude/Cursor 等）能够直接操作 Archery 平台。

## 一键安装（推荐）

作为 [Agent Skill](https://skills.sh/) 安装，自动配置 MCP：

```bash
npx skills add ckall/archery-mcp-server
```

安装后在 MCP 配置中填入你的 Archery 连接信息即可使用。

## 手动安装

### 方式一：uvx（无需预装，推荐）

```json
{
  "mcpServers": {
    "archery": {
      "command": "uvx",
      "args": ["archery-mcp-server@latest"],
      "env": {
        "ARCHERY_BASE_URL": "http://archery.example.com",
        "ARCHERY_USERNAME": "admin",
        "ARCHERY_PASSWORD": "your_password"
      }
    }
  }
}
```

### 方式二：pip install

```bash
pip install archery-mcp-server
```

然后配置 MCP：

```json
{
  "mcpServers": {
    "archery": {
      "command": "archery-mcp",
      "env": {
        "ARCHERY_BASE_URL": "http://archery.example.com",
        "ARCHERY_USERNAME": "admin",
        "ARCHERY_PASSWORD": "your_password"
      }
    }
  }
}
```

## 环境变量

| 变量 | 必填 | 说明 |
|------|------|------|
| `ARCHERY_BASE_URL` | ✅ | Archery 平台地址 |
| `ARCHERY_USERNAME` | ✅ | 登录用户名 |
| `ARCHERY_PASSWORD` | ✅ | 登录密码 |

## 功能覆盖（26 个工具）

| 模块 | 工具数 | 能力 |
|------|--------|------|
| SQL 工单管理 | 6 | 提交/查看/审核/执行/待办/日志 |
| SQL 审核 | 1 | 语法检查（goInception） |
| SQL 查询 | 6 | 执行查询/浏览资源/表结构/历史/收藏 |
| 实例管理 | 6 | CRUD/资源浏览/按表名查实例 |
| 用户管理 | 4 | CRUD |
| 资源组/权限组 | 4 | 列表/创建 |

详细工具说明见 [SKILL.md](./SKILL.md)。

## 项目结构

```
archery-mcp-server/
├── SKILL.md                    # Agent Skill 定义（安装即用）
├── pyproject.toml              # Python 包配置
├── mcp.json                    # MCP 配置示例
└── src/archery_mcp/
    ├── __init__.py
    ├── client.py               # Archery API 客户端（JWT认证）
    └── server.py               # MCP Server（26个工具）
```

## 开发

```bash
# 克隆
git clone https://github.com/ckall/archery-mcp-server.git
cd archery-mcp-server

# 安装开发依赖
pip install -e .

# 本地运行
export ARCHERY_BASE_URL=http://localhost:9123
export ARCHERY_USERNAME=admin
export ARCHERY_PASSWORD=admin
archery-mcp
```

## 兼容性

- Python 3.10+
- Archery 1.8+（需启用 REST API）
- 支持所有 MCP 兼容的 AI IDE：Kiro、Claude Code、Cursor、Windsurf 等

## License

MIT