Metadata-Version: 2.4
Name: pingcode-mcp
Version: 0.1.0
Summary: MCP server for PingCode project management — manage projects, sprints, and work items via any MCP client.
Project-URL: Repository, https://github.com/RunVid/pingcode-mcp
Project-URL: Issues, https://github.com/RunVid/pingcode-mcp/issues
Author: RunVid
License-Expression: MIT
Keywords: agile,mcp,pingcode,project-management,scrum
Classifier: Development Status :: 4 - Beta
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: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: fastmcp<3,>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: tenacity>=8.2.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.22; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# PingCode MCP Server

MCP server for [PingCode](https://pingcode.com) project management. Manage projects, sprints, and work items (stories, bugs, tasks, epics) from any MCP client.

Built with Python, OAuth2 authentication, and the [FastMCP](https://github.com/jlowin/fastmcp) framework.

## Features

- **10 MCP tools** covering full CRUD for work items, sprint listing, project listing, and metadata queries
- **OAuth2 client credentials** authentication (no browser required)
- **Auto-pagination** for large result sets
- **Retry with exponential backoff** on transient failures
- **Docker support** for one-command deployment

## Quick Start

### 1. Get PingCode OAuth2 Credentials

In PingCode admin panel: **Settings → Applications → Create App** to obtain `client_id` and `client_secret`.

### 2. Configure

```bash
cp .env.example .env
# Edit .env with your credentials
```

### 3. Run

**Option A: Docker (recommended)**

```bash
docker compose up --build -d
```

**Option B: Local (development)**

```bash
pip install -e ".[dev]"
pingcode-mcp-server
```

### 4. Connect to Claude Code

Add to `~/.claude.json`:

**Docker mode:**
```json
{
  "mcpServers": {
    "pingcode-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env-file", "/path/to/pingcode-mcp/.env", "pingcode-mcp:latest"]
    }
  }
}
```

**Local mode (with uv):**
```json
{
  "mcpServers": {
    "pingcode-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/pingcode-mcp", "pingcode-mcp-server"]
    }
  }
}
```

## Tools

| Tool | Description |
|------|-------------|
| `pingcode_list_projects` | List accessible projects |
| `pingcode_list_sprints` | List sprints in a project |
| `pingcode_list_work_items` | Search/filter work items |
| `pingcode_get_work_item` | Get work item details |
| `pingcode_create_work_item` | Create a work item |
| `pingcode_update_work_item` | Update work item fields |
| `pingcode_delete_work_item` | Delete a work item |
| `pingcode_get_work_item_types` | Get types (story, bug, task...) |
| `pingcode_get_work_item_states` | Get states for a type |
| `pingcode_get_work_item_priorities` | Get priority levels |

## Configuration

| Environment Variable | Required | Default | Description |
|---------------------|----------|---------|-------------|
| `PINGCODE_CLIENT_ID` | Yes | — | OAuth2 client ID |
| `PINGCODE_CLIENT_SECRET` | Yes | — | OAuth2 client secret |
| `PINGCODE_BASE_URL` | No | `https://open.pingcode.com` | API base URL |
| `PINGCODE_DEFAULT_PROJECT_ID` | No | — | Default project ID |

## Testing

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run unit tests
pytest tests/unit/

# Run unit tests with coverage
pytest tests/unit/ --cov=pingcode_mcp --cov-report=term-missing

# Run E2E tests (requires .env with real credentials)
pytest -m e2e
```

## Project Structure

```
src/pingcode_mcp/
├── config.py      # Environment variable loading
├── client.py      # Async PingCode API client (OAuth2, retry, pagination)
├── server.py      # FastMCP entry point
└── tools/
    ├── projects.py    # Project listing
    ├── sprints.py     # Sprint listing
    ├── work_items.py  # Work item CRUD
    └── metadata.py    # Types, states, priorities
```

## License

MIT
