Metadata-Version: 2.4
Name: artguru-mcp
Version: 0.1.0
Summary: MCP server for the Artguru Open API Platform.
Project-URL: Documentation, https://x6oynfyxq3.apifox.cn/authentication-7269269m0
Project-URL: Source, https://github.com/artguru/artguru-mcp
Author: Artguru MCP Maintainers
License-Expression: MIT
License-File: LICENSE
Keywords: ai,artguru,image,mcp,openapi
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]>=1.6.0
Requires-Dist: pydantic>=2.7.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.25.0; extra == 'dev'
Requires-Dist: pytest>=8.2.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Description-Content-Type: text/markdown

# Artguru MCP

Artguru MCP is a Python MCP server for the Artguru Open API Platform. It wraps
Artguru image APIs and exposes them as MCP tools for clients such as Codex,
Claude Desktop, and other MCP-compatible agents.

中文版本请见 [README.zh-CN.md](README.zh-CN.md).

## Requirements

- Python 3.11 or later.
- An Artguru API key.

## Installation

Install the package from PyPI:

```bash
pip install artguru-mcp
```

## MCP client configuration

Add the server to your MCP client configuration:

```json
{
  "mcpServers": {
    "artguru-mcp": {
      "command": "artguru-mcp",
      "env": {
        "ARTGURU_API_KEY": "your_api_key"
      }
    }
  }
}
```

You can also pass `api_key` directly to each tool. Using `ARTGURU_API_KEY` is
recommended because it keeps secrets out of prompts and tool arguments.

## Tools

- `artguru_get_credits`: Get total, used, and remaining account credits.
- `artguru_upload_image`: Upload a local image and return an Artguru image URL.
- `artguru_photo_enhance`: Start a photo enhancement task from an image URL.
- `artguru_image_to_image`: Start an image-to-image generation task.
- `artguru_get_task_status`: Check a task by business type and task ID.
- `artguru_photo_enhance_with_progress`: Upload a local image, create an
  enhancement task, poll status, and return every step in `steps`.
- `artguru_image_to_image_with_progress`: Upload a local image, create an
  image-to-image task, poll status, and return every step in `steps`.

Use the `_with_progress` tools when you want the client to show the full
workflow. Their response includes step events such as `upload_started`,
`upload_succeeded`, `task_create_started`, `task_create_succeeded`,
`poll_started`, `poll_attempt`, `poll_succeeded`, `poll_failed`, and
`poll_timeout`.

If upload, task creation, or polling fails, the tool returns
`status: "FAILED"` with a failure event and an `error` message. If polling
does not finish within `max_poll_attempts`, the tool returns
`status: "TIMEOUT"`.

## Environment variables

- `ARTGURU_API_KEY`: Required Artguru API key.
- `ARTGURU_BASE_URL`: Optional API base URL. Defaults to
  `https://api.artguru.ai/`.

## Development

Install development dependencies and run checks with `uv`:

```bash
uv run --extra dev python -m pytest
uv run --extra dev ruff check .
uv build
```

## Project links

- Documentation: <https://x6oynfyxq3.apifox.cn/authentication-7269269m0>
