Metadata-Version: 2.4
Name: issuedeck
Version: 0.3.0
Summary: Local-first issue deck for AI coding agents and human developers
Project-URL: Homepage, https://github.com/xq520mmy/IssueDeck
Project-URL: Repository, https://github.com/xq520mmy/IssueDeck
Project-URL: Issues, https://github.com/xq520mmy/IssueDeck/issues
Project-URL: Changelog, https://github.com/xq520mmy/IssueDeck/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/xq520mmy/IssueDeck#readme
Author: IssueDeck contributors
License-Expression: MIT
License-File: LICENSE
Keywords: developer-tools,fastapi,issue-tracker,mcp,sqlite
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
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 :: Software Development
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.19
Requires-Dist: alembic>=1.13
Requires-Dist: fastapi>=0.136.1
Requires-Dist: fastmcp>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: jinja2>=3.1
Requires-Dist: markdown-it-py>=3.0
Requires-Dist: pydantic-settings>=2.14.0
Requires-Dist: pydantic>=2.13.3
Requires-Dist: python-frontmatter>=1.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: sqlalchemy[asyncio]>=2.0.49
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: uvicorn[standard]>=0.46.0
Description-Content-Type: text/markdown

# IssueDeck

English | [简体中文](README.zh-CN.md)

[![CI](https://github.com/xq520mmy/IssueDeck/actions/workflows/ci.yml/badge.svg)](https://github.com/xq520mmy/IssueDeck/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/xq520mmy/IssueDeck?display_name=tag)](https://github.com/xq520mmy/IssueDeck/releases)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

<p align="center">
  <img src="docs/assets/issuedeck-social-preview.png" alt="IssueDeck: a local-first issue deck for humans and AI coding agents" width="100%">
</p>

**Lighter than Jira. More stable than Markdown.**

IssueDeck is a local-first, self-hosted issue deck for small teams and AI
coding workflows. It gives multiple projects one shared FastAPI + SQLite
tracker, a web dashboard for humans, and MCP tools for coding agents.

## Why IssueDeck

- Replace project-specific Markdown trackers with one structured source of
  truth that stays close to code, commits, branches, and releases.
- Give humans and coding agents the same workflow instead of maintaining a
  dashboard in one place and agent instructions in another.
- Start safely with demo data, then add real project configs when you are ready.

![IssueDeck dashboard demo](docs/assets/issuedeck-demo.gif)

See the [screenshot gallery](docs/gallery.md) for list, kanban, detail,
search, and project creation surfaces.
Daily triage shortcuts are documented in
[Keyboard Shortcuts](docs/keyboard-shortcuts.md).

## Features

- Agent-ready: MCP tools let coding agents create, update, search, relate, and
  ship tracked work without scraping Markdown.
- Multi-project: one SQLite DB holds items for any number of projects, keyed by
  `project_key`. Each project has its own `kinds`, `statuses`, `branches`,
  and numeric ID prefix (e.g. `FEAT-0001`, `BUG-0003`).
- Full-text search via SQLite FTS5.
- Bidirectional relationships (`blocks`/`blocked_by`, `related_to`).
- External links for GitHub issues, pull requests, commits, and other review context.
- Item activity timeline with automatic lifecycle events and manual comments.
- Signed lifecycle webhooks for downstream automation on create, update, ship,
  delete, and restore events.
- Built-in dashboard work queues for backlog, active, blocked, ready-to-ship,
  done, deleted, and recently touched items.
- Project-scoped saved dashboard filters for reusable views such as active
  bugs, blocked work, release queues, and tag-specific searches.
- Soft delete + restore.
- Ship records with version + commits, queryable by shipped branch.
- Markdown export (one file per item) and changelog rendering.
- Frontmatter migration from existing Markdown trackers.
- Server-rendered dashboard with list, kanban, detail, search, and create/edit flows.
- Keyboard-friendly dashboard triage for search, filters, create, and item focus.
- Dashboard project creation and language switch foundation.
- MCP tools for coding-agent workflows.

## Requirements

- Python 3.11+
- [uv](https://docs.astral.sh/uv/)
- Docker, optional for container deployment
- Node.js 20+, only needed when changing dashboard styles

## Quickstart

Try the latest GitHub version without cloning:

```bash
uvx --from git+https://github.com/xq520mmy/IssueDeck issuedeck demo --open
```

After the PyPI package is published, the command becomes:

```bash
uvx issuedeck demo --open
```

Start a local dashboard with fake demo data:

```bash
uv run issuedeck demo
```

This creates a local `server.toml` if one does not exist, applies database
migrations, seeds the `example` project with fake items, and starts the server.
Then open `http://127.0.0.1:8765/dashboard/example` and sign in with
`issuedeck-local-token`.

To open the dashboard automatically:

```bash
uv run issuedeck demo --open
```

Health endpoints:

```bash
curl http://127.0.0.1:8765/healthz
curl http://127.0.0.1:8765/readyz
```

If the first run fails because of a missing `uv`, an occupied port, a token
problem, SQLite migrations, or Docker Compose startup, see the
[first-run troubleshooting guide](docs/troubleshooting.md).

Dashboard CSS is committed in the repository, so Node is not required to run
IssueDeck. If you change dashboard templates, helper class maps, or
`tailwind.config.cjs`, rebuild the CSS with `npm ci && npm run build:css`.

## Configure

`server.toml` controls the server:

```toml
host = "0.0.0.0"
port = 8765
api_token = "change-me-in-production"
data_dir = "./data"
projects_dir = "./projects"
```

For real use, set the token through the environment instead of committing it:

```bash
export ISSUEDECK_API_TOKEN="your-secret-token"
```

PowerShell:

```powershell
$env:ISSUEDECK_API_TOKEN = "your-secret-token"
```

`api_token` remains the backwards-compatible admin token. For multiple clients,
add scoped tokens:

```toml
[[tokens]]
name = "readonly"
token = "replace-with-readonly-token"
scopes = ["read"]

[[tokens]]
name = "agent"
token = "replace-with-agent-token"
scopes = ["agent"]

[[tokens]]
name = "admin-dashboard"
token = "replace-with-admin-token"
scopes = ["admin"]
```

`read` tokens can call read-only API endpoints. `agent` tokens can read and
write REST API resources for MCP/coding-agent workflows. `admin` tokens have
full API access and can sign in to the dashboard.

Optional signed lifecycle webhooks can notify downstream automation when items
are created, updated, shipped, deleted, or restored; see
[Lifecycle Webhooks](docs/webhooks.md).

Project files live in `projects/*.toml`. Each file defines one project and
must use the same file stem, `key`, and dashboard URL segment. The repository
includes `projects/example.toml` so the quickstart works immediately:

```toml
key = "myproject"
name = "My Project"
```

Dashboard: `http://127.0.0.1:8765/dashboard/myproject`

## Demo Data

Use fake data for screenshots, docs, or a clean local demo:

```bash
uv run issuedeck seed-demo --config server.toml --project-key example
```

If the target project already has items, the command refuses to overwrite it.
To intentionally replace that project's items, add `--force-reset`.

For the full first-run flow, prefer `uv run issuedeck demo`; it creates config,
runs migrations, seeds fake data, and starts the dashboard.

## Run the server

```bash
# Apply database migrations first
uv run alembic upgrade head

# Start the server
export ISSUEDECK_API_TOKEN="your-secret-token"
uv run issuedeck serve --config server.toml
```

PowerShell:

```powershell
$env:ISSUEDECK_API_TOKEN = "your-secret-token"
uv run issuedeck serve --config server.toml
```

The dashboard uses the same shared token as the API. Open the dashboard URL,
enter `ISSUEDECK_API_TOKEN`, and IssueDeck will create an HTTP-only browser
session cookie. API and MCP clients should keep using the `Authorization:
Bearer <token>` header.

## Docker

The default Compose file pulls the published image from GitHub Container
Registry:

```bash
cp server.toml.example server.toml
cp .env.example .env
docker compose pull
docker compose up -d
```

Open `http://127.0.0.1:8765/dashboard/example` and sign in with
`ISSUEDECK_API_TOKEN` from `.env`.

To run a locally built image from source instead:

```bash
docker build -t issuedeck:local .
ISSUEDECK_IMAGE=issuedeck:local docker compose up -d
```

For offline or server deployment details, see [DEPLOY.md](DEPLOY.md). A longer
Chinese deployment guide is available at
[docs/deployment.zh.md](docs/deployment.zh.md).

## MCP stdio process

For client-specific examples, see [MCP Client Setup](docs/mcp-clients.md).

Generic stdio config:

```json
{
  "mcpServers": {
    "issuedeck": {
      "command": "uv",
      "args": ["run", "python", "-m", "issuedeck.mcp"],
      "env": {
        "ISSUEDECK_BASE_URL": "http://127.0.0.1:8765",
        "ISSUEDECK_TOKEN": "your-secret-token"
      }
    }
  }
}
```

> **Note:** The MCP client reads `ISSUEDECK_TOKEN`; the server reads
> `ISSUEDECK_API_TOKEN`. They may hold the same value but the env var names
> differ by design (client/server are separate processes).

12 tools: `list_projects`, `get_project_config`, `create_item`, `update_item`,
`ship_item`, `append_item_event`, `delete_item`, `get_item`, `list_items`,
`search_items`, `add_relationship`, `remove_relationship`.

The MCP process reads `ISSUEDECK_BASE_URL` and `ISSUEDECK_TOKEN`, then talks to
the REST server over HTTP. It does not access SQLite directly.

## Migrate from Markdown Frontmatter

```bash
uv run issuedeck migrate \
  --config server.toml \
  --from-frontmatter /path/to/markdown-tracker \
  --project-key myproject
```

Add `--dry-run` to preview without writing. Add `--force-reset` to wipe existing items first.
The importer accepts the canonical schema plus common aliases such as `type`,
`state`, and `labels`; see
[Markdown Frontmatter Import](docs/markdown-frontmatter-import.md) for the full
schema and custom alias options.

## Export

```bash
uv run issuedeck export \
  --config server.toml \
  --project-key myproject \
  --out ./export
```

Writes one `.md` file per item with YAML frontmatter.

## Development

```bash
uv sync
uv run pytest
uv run ruff check .
```

For dashboard UI work:

```bash
npm ci
npm run build:css
```

Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
Dashboard UI work should follow [DESIGN.md](DESIGN.md).
See [ROADMAP.md](ROADMAP.md) for planned work and contribution areas.
For support and issue-reporting guidance, see [SUPPORT.md](SUPPORT.md).
For sensitive vulnerabilities, follow [SECURITY.md](SECURITY.md).
For PyPI Trusted Publishing setup, see
[docs/pypi-publishing.md](docs/pypi-publishing.md).

## License

MIT. See [LICENSE](LICENSE).
Vendored dashboard browser assets are listed in
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
