内容
# AppDog
[](https://github.com/rodolphebarbanneau/appdog/actions?query=event%3Apush+branch%3Amain+workflow%3Aci)
[](https://codecov.io/gh/rodolphebarbanneau/appdog)
[](https://pypi.python.org/pypi/appdog)
[](https://pypi.python.org/pypi/appdog)
[](https://pepy.tech/project/appdog)
[](https://github.com/rodolphebarbanneau/appdog/blob/main/LICENSE)
轻松组合和生成异步 API 客户端和 MCP 服务器，适用于任何 OpenAPI 规范。
<br>
<p align="center">
<img src="https://raw.githubusercontent.com/rodolphebarbanneau/appdog/refs/heads/main/docs/appdog.gif" alt="AppDog demo">
</p>
## 概述
AppDog 是一个 Python 包，通过以下方式简化了基于 OpenAPI 的 API 工作：
- 自动从 OpenAPI 规范生成完全类型化的 Python 客户端
- 为 API 集成创建即用的 MCP（模型上下文协议）服务器
- 在单个项目中管理多个 API 客户端，并锁定版本
- 提供用于添加、删除、管理 API 客户端和安装 MCP 服务器的简单命令行界面
## 安装
```bash
uv add appdog
```
## 快速入门
### 初始化项目
```bash
# 在当前目录中创建新项目
appdog init
# 或指定项目目录
appdog init --project /path/to/project
```
### 添加 API 客户端
```bash
# 从 OpenAPI 规范 URL 或文件添加新的 API 客户端
appdog add petstore --uri https://petstore3.swagger.io/api/v3/openapi.json
```
### 列出和显示可用 API
```bash
# 列出项目中的所有 API 客户端
appdog list
# 显示特定 API 客户端的详细信息
appdog show petstore
```
### 升级 API 客户端
```bash
# 将 API 客户端与项目注册表同步
appdog sync --upgrade
# 锁定 API 客户端
appdog lock --upgrade
```
### 生成 MCP 服务器
```bash
# 生成并安装具有所有已注册 API 的 MCP 服务器
appdog mcp install -n "我的 API 服务器"
# 或直接运行服务器
appdog mcp run -n "我的 API 服务器"
# 或在开发模式下运行，带有检查器
appdog mcp dev -n "我的 API 服务器"
```
## 项目结构
初始化项目并添加 API 后，您的项目将具有：
```
project/
├── apps.yaml # 已安装的 API appdog 设置（自动生成）
├── apps.lock # 锁定文件，包含应用规格和哈希值（自动生成）
└── ... # 项目文件
```
## 使用生成的客户端
添加 API 客户端后，您可以在代码中导入并使用它：
```python
# 导入生成的客户端
import appdog.petstore
# 使用客户端
async def main() -> None:
async with appdog.petstore.client as client:
pets = await client.get_pet_find_by_status(status='available')
print(pets)
```
并组合您自己的 MCP 服务器：
```python
import appdog.petstore
from mcp.server import FastMCP
mcp = FastMCP()
@mcp.tool()
async def hello_petstore() -> str:
async with appdog.petstore.client as client:
pets = await client.get_pet_find_by_status(status='available')
return pets
```
## 环境变量
可以使用环境变量配置 API 凭证：
```
APPDOG_<CLIENT_NAME>_TOKEN=your_token
APPDOG_<CLIENT_NAME>_API_KEY=your_api_key
```
## MCP 集成
该包包含对 MCP 服务器生成的完全支持：
1. 生成 MCP 服务器文件：
```bash
appdog mcp install -n "我的 API 服务器"
```
2. 与 FastMCP 或其他 MCP 客户端一起使用：
```python
from appdog import Project
from mcp.server import FastMCP
mcp = FastMCP()
project = Project.load(project_dir=PROJECT_DIR)
project.mount(mcp)
```
## 命令行界面用法
### 全局选项
- `--verbose`, `-v`: 启用详细输出
- `--debug`, `-d`: 启用所有调试日志，包括依赖项
- `--project`, `-p`: 指定项目目录（默认为当前目录）
### 命令
#### 显示 CLI 版本
```bash
appdog version
```
#### 初始化项目
```bash
appdog init [--force] [--project PATH]
```
- `--force`: 强制初始化，即使配置文件已经存在
#### 添加 API 客户端
```bash
appdog add NAME --uri URI [--base-url URL] [OPTIONS]
```
- `NAME`: 应用程序名称
- `--uri`: OpenAPI 规范 URL 或文件路径
- `--base-url`: API 调用基准 URL
- `--include-methods`: 要包含的方法
- `--exclude-methods`: 要排除的方法
- `--include-tags`: 要包含的标签
- `--exclude-tags`: 要排除的标签
- `--force`: 如果应用程序已存在且 URI 不同，则覆盖它
- `--frozen`: 跳过在项目锁定文件中添加应用程序规范
- `--upgrade`: 强制升级应用程序规范
- `--sync`: 将应用程序规范与项目注册表同步
#### 删除 API 客户端
```bash
appdog remove NAME [OPTIONS]
```
- `NAME`: 应用程序名称
- `--frozen`: 跳过从项目锁定文件中删除应用程序规范
- `--sync`: 将应用程序删除与项目注册表同步
#### 列出 API 客户端
```bash
appdog list [--project PATH]
```
#### 显示 API 客户端详细信息
```bash
appdog show NAME [--project PATH]
```
- `NAME`: 应用程序名称
#### 锁定 API 规格
```bash
appdog lock [OPTIONS]
```
- `--force`: 如果应用程序存在且 URI 不同，则覆盖它
- `--upgrade`: 如果应用程序存在且 URI 不同，则覆盖应用程序规范
#### 同步 API 客户端
```bash
appdog sync [OPTIONS]
```
- `--force`: 如果应用程序存在且 URI 不同，则覆盖它
- `--frozen`: 跳过更新项目锁定文件中的应用程序规范
- `--upgrade`: 强制升级应用程序规范
#### 生成 MCP 服务器
```bash
appdog mcp [COMMAND] [OPTIONS]
```
命令：
- `install`: 在 MCP 客户端中安装应用程序
- `run`: 在生产模式下运行 MCP 应用程序
- `dev`: 在开发模式下运行 MCP 应用程序，带有检查器
每个命令都支持特定的选项：
##### 常见选项（所有命令）
- `--name`, `-n`: MCP 服务器名称（默认为 "AppDog MCP Server"）
- `--force`: 如果文件存在，则覆盖服务器文件
- `--project`, `-p`: 项目目录（默认为当前目录）
- `--output`, `-o`: MCP 服务器文件的输出路径
##### 安装命令
```bash
appdog mcp install [OPTIONS]
```
- `--env-var`, `-v`: 格式为 KEY=VALUE 的环境变量
- `--env-file`, `-f`: 包含 KEY=VALUE 对的环境文件
- `--with`: 在开发模式下安装的其他包
- `--with-editable`, `-e`: 以可编辑模式安装的本地包
##### 运行命令
```bash
appdog mcp run [OPTIONS]
```
- `--transport`, `-t`: 用于 MCP 运行的传输（stdio 或 sse）
##### 开发命令
```bash
appdog mcp dev [OPTIONS]
```
- `--with`: 在开发模式下安装的其他包
- `--with-editable`, `-e`: 以可编辑模式安装的本地包
## 高级用法
### 客户端配置
创建自定义的 `apps.yaml` 以配置您的 API 客户端：
```yaml
petstore:
uri: https://petstore3.swagger.io/api/v3/openapi.json
base_url: https://petstore3.swagger.io/api/v3
include_tags:
- pet
- store
```
### 自定义身份验证
> 有关 MCP 使用，请参阅 [环境变量部分](#环境变量)
使用自定义身份验证创建客户端：
```python
from appdog.petstore import PetstoreClient
# 自定义 API 密钥
client = PetstoreClient(api_key="YOUR_API_KEY")
# 自定义标头
client = PetstoreClient(
headers={"Authorization": "Bearer YOUR_TOKEN"}
)
```
## 贡献
有关为项目做出贡献的信息，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
该项目根据 MIT 许可证授权 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
MCP 市场