Metadata-Version: 2.4
Name: appdog
Version: 0.1.0b6
Summary: Generate async API clients and MCP servers from OpenAPI specifications
Project-URL: Homepage, https://github.com/rodolphebarbanneau/appdog
Project-URL: Documentation, https://github.com/rodolphebarbanneau/appdog#readme
Project-URL: Issues, https://github.com/rodolphebarbanneau/appdog/issues
Project-URL: Source, https://github.com/rodolphebarbanneau/appdog
Author: Rodolphe Barbanneau
License: MIT License
        
        Copyright (c) 2023 Rodolphe Barbanneau
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: api,client,mcp,openapi,server
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Internet
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: datamodel-code-generator>=0.25.2
Requires-Dist: httpx>=0.26.0
Requires-Dist: jinja2>=3.1.3
Requires-Dist: mcp>=1.6.0
Requires-Dist: pydantic-core>=2.33.1
Requires-Dist: pydantic-settings>=2.8.1
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
Requires-Dist: types-requests>=2.31.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
Requires-Dist: pytest-cov>=6.1.1; extra == 'test'
Requires-Dist: pytest-mock>=3.14.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Description-Content-Type: text/markdown

# AppDog

[![ci](https://img.shields.io/github/actions/workflow/status/rodolphebarbanneau/appdog/ci.yml?branch=main&logo=github&label=ci)](https://github.com/rodolphebarbanneau/appdog/actions?query=event%3Apush+branch%3Amain+workflow%3Aci)
[![cov](https://codecov.io/gh/rodolphebarbanneau/appdog/branch/main/graph/badge.svg)](https://codecov.io/gh/rodolphebarbanneau/appdog)
[![pypi](https://img.shields.io/pypi/v/appdog.svg)](https://pypi.python.org/pypi/appdog)
[![versions](https://img.shields.io/pypi/pyversions/appdog.svg)](https://pypi.python.org/pypi/appdog)
[![downloads](https://static.pepy.tech/badge/appdog/month)](https://pepy.tech/project/appdog)
[![license](https://img.shields.io/github/license/rodolphebarbanneau/appdog.svg)](https://github.com/rodolphebarbanneau/appdog/blob/main/LICENSE)

Compose and generate effortlessly async API clients and MCP servers from any OpenAPI specifications.

## Overview

AppDog is a Python package that simplifies working with OpenAPI-based APIs by:

- Automatically generating fully typed Python clients from OpenAPI specifications
- Creating ready-to-use MCP (Model Context Protocol) servers for API integrations
- Managing multiple API clients in a single project with version locking
- Providing a simple CLI for adding, removing, managing API clients, and installing MCP servers

## Installation

```bash
uv add appdog
```

## Quick Start

### Initialize a project

```bash
# Create a new project in the current directory
appdog init

# Or specify a project directory
appdog init --project /path/to/project
```

### Add an API client

```bash
# Add a new API client from an OpenAPI spec URL or file
appdog add petstore --uri https://petstore3.swagger.io/api/v3/openapi.json
```

### List and show available APIs

```bash
# List all API clients in the project
appdog list

# Show details for a specific API client
appdog show petstore
```

### Upgrade API clients

```bash
# Sync API clients with the project registry
appdog sync --upgrade

# Lock API clients
appdog lock --upgrade
```

### Generate an MCP server

```bash
# Generate and install an MCP server with all registered APIs
appdog mcp install -n "My API Server"

# Or run the server directly
appdog mcp run -n "My API Server"

# Or run in development mode with inspector
appdog mcp dev -n "My API Server"
```

## Project Structure

After initializing a project and adding APIs, your project will have:

```
project/
├── apps.yaml     # Installed API appdog settings (auto-generated)
├── apps.lock     # Lock file with app specs and hashes (auto-generated)
└── ...           # Project files
```

## Using Generated Clients

After adding an API client, you can import and use it in your code:

```python
# Import generated client
import appdog.petstore

# Use the client
async def main() -> None:
    async with appdog.petstore.client as client:
        pets = await client.get_pet_find_by_status(status='available')
        print(pets)
```

And compose your own MCP server:

```python
import appdog.petstore
from fastmcp 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
```

## Environment Variables

API credentials can be configured using environment variables:

```
APPDOG_<CLIENT_NAME>_TOKEN=your_token
APPDOG_<CLIENT_NAME>_API_KEY=your_api_key
```

## MCP Integration

The package includes full support for MCP server generation:

1. Generate an MCP server file:
    ```bash
    appdog mcp install -n "My API Server"
    ```

2. Use with FastMCP or other MCP clients:
    ```python
    from appdog import Project
    from fastmcp import FastMCP
  
    mcp = FastMCP()

    project = Project.load(project_dir=PROJECT_DIR)
    project.mount(mcp)
    ```

## CLI Usage

### Global Options

- `--verbose`, `-v`: Enable verbose output
- `--debug`, `-d`: Enable all debug logs, including dependencies
- `--project`, `-p`: Specify project directory (defaults to current directory)

### Commands

#### Show CLI version

```bash
appdog version
```

#### Initialize Project

```bash
appdog init [--force] [--project PATH]
```

- `--force`: Force initialization even if config already exists

#### Add API Client

```bash
appdog add NAME --uri URI [--base-url URL] [OPTIONS]
```

- `NAME`: Application name
- `--uri`: OpenAPI specification URL or file path
- `--base-url`: Base URL for API calls
- `--include-methods`: Methods to include
- `--exclude-methods`: Methods to exclude
- `--include-tags`: Tags to include
- `--exclude-tags`: Tags to exclude
- `--force`: Overwrite application if it already exists with a different URI
- `--frozen`: Skip adding application specification in project lock file
- `--upgrade`: Force upgrading application specification
- `--sync`: Sync application specification with project registry

#### Remove API Client

```bash
appdog remove NAME [OPTIONS]
```

- `NAME`: Application name
- `--frozen`: Skip removing application specification from project lock file
- `--sync`: Sync application removal with project registry

#### List API Clients

```bash
appdog list [--project PATH]
```

#### Show API Client Details

```bash
appdog show NAME [--project PATH]
```

- `NAME`: Application name

#### Lock API Specifications

```bash
appdog lock [OPTIONS]
```

- `--force`: Overwrite application if it exists with a different URI
- `--upgrade`: Overwrite application specification with a different URI

#### Sync API Clients

```bash
appdog sync [OPTIONS]
```

- `--force`: Overwrite application if it exists with a different URI
- `--frozen`: Skip updating application specification in project lock file
- `--upgrade`: Force upgrading application specification

#### Generate MCP Server

```bash
appdog mcp [COMMAND] [OPTIONS]
```

Commands:
- `install`: Install applications in MCP client
- `run`: Run MCP applications in production mode
- `dev`: Run MCP applications in development mode with inspector

Each command supports specific options:

##### Common Options (all commands)
- `--name`, `-n`: Name of the MCP server (default: "AppDog MCP Server")
- `--force`: Overwrite server file if it exists
- `--project`, `-p`: Project directory (defaults to current)
- `--output`, `-o`: Output path for MCP server file

##### Install Command
```bash
appdog mcp install [OPTIONS]
```
- `--env-var`, `-v`: Environment variables in KEY=VALUE format
- `--env-file`, `-f`: Environment file with KEY=VALUE pairs
- `--with`: Additional packages to install in dev mode
- `--with-editable`, `-e`: Local packages to install in editable mode

##### Run Command
```bash
appdog mcp run [OPTIONS]
```
- `--transport`, `-t`: Transport to use for MCP run (stdio or sse)

##### Dev Command
```bash
appdog mcp dev [OPTIONS]
```
- `--with`: Additional packages to install in dev mode
- `--with-editable`, `-e`: Local packages to install in editable mode

## Advanced Usage

### Client Configuration

Create a custom `apps.yaml` to configure your API clients:

```yaml
petstore:
  uri: https://petstore3.swagger.io/api/v3/openapi.json
  base_url: https://petstore3.swagger.io/api/v3
  include_tags:
    - pet
    - store
```

### Custom Authentication

> For MCP usage, see [environment variables section](#environment-variables)

Create a client with custom authentication:

```python
from appdog.petstore import PetstoreClient

# Custom API key
client = PetstoreClient(api_key="YOUR_API_KEY")

# Custom headers
client = PetstoreClient(
    headers={"Authorization": "Bearer YOUR_TOKEN"}
)
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for information on contributing to the project.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
