Metadata-Version: 2.4
Name: agileforagents
Version: 0.3.0
Summary: Zero-config MCP server that turns prompts into verified agile task boards for AI coding agents
License: MIT
Project-URL: Homepage, https://github.com/FAJU85/AgileForAgents
Project-URL: Repository, https://github.com/FAJU85/AgileForAgents
Project-URL: Issues, https://github.com/FAJU85/AgileForAgents/issues
Keywords: mcp,agile,ai-agents,claude-code,cursor,codex
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: Topic :: Software Development :: Build Tools
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.9.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: pip-audit>=2.7.0; extra == "dev"

# AgileForAgents

**Turn any project prompt into a verified, sprint-ready agile task board — right inside your AI coding agent.**

AgileForAgents is a zero-config [MCP](https://modelcontextprotocol.io) server for
Claude Code, Cursor, Codex CLI, and any MCP-compatible host. You describe a project
in your IDE as you normally would; AgileForAgents turns it into a structured agile
board (epics → sprints → user stories → subtasks) where **every subtask has an
observable done-criteria** and **every assumption is made explicit** — following
Andrej Karpathy's Spec methodology.

## How it works

```
┌──────────────────────────┐   stdio    ┌────────────────────────┐   HTTPS    ┌──────────────────────────────┐
│  Your IDE                │◀──────────▶│  agileforagents        │───────────▶│  Hosted backend (HF Space)   │
│  Claude Code / Cursor /  │  MCP tool  │  MCP server            │  /api/     │  • runs a free HF model       │
│  Codex — you type here   │  call      │  (stdlib-only client)  │  generate  │  • holds the token server-side│
└──────────────────────────┘            └────────────────────────┘◀───────────│  • returns a verified board   │
                                                                                └───────────────┬──────────────┘
                                                                                                │ logs metrics
                                                                                                ▼
                                                                                  ┌──────────────────────────┐
                                                                                  │  Gradio Control Panel     │
                                                                                  │  (monitoring dashboard,   │
                                                                                  │   no prompt input)        │
                                                                                  └──────────────────────────┘
```

- **You never leave your IDE.** Prompts come from your editor through the MCP tool —
  not from a web form.
- **No API key, no token, no heavy dependencies.** The MCP server installs with just
  the MCP SDK + pydantic. All model inference happens on the hosted backend, which
  holds the Hugging Face token as a server-side secret.
- **The Gradio Space is a control panel**, not an input form — it shows how the
  generator is performing (volume, average verification score, recent activity).
- **Works offline, degraded.** If the backend is unreachable, a local heuristic
  fallback still returns a valid scaffold board so the tool never hard-fails.

## Install

```bash
pip install agileforagents
```

Then register the `agileforagents` stdio server with your MCP host.

**Claude Code** (`~/.claude/mcp.json` or project `.mcp.json`):

```json
{
  "mcpServers": {
    "agileforagents": {
      "command": "agileforagents"
    }
  }
}
```

**Cursor / Codex CLI:** point your MCP config at the `agileforagents` command. No
environment variables are required.

## Tools

| Tool | What it does |
|---|---|
| `generate_agile_tasks` | Turn a prompt into a verified agile board. Args: `prompt`, `format` (`claude` \| `json` \| `cursor`), `detail_level` (`standard` \| `detailed`). |
| `get_agent_rules` | Return the AgileForAgents working protocol to paste into `CLAUDE.md` / `.cursorrules`. |
| `feedback_stats` | Local generation count + backend health. |

## Configuration (optional)

The MCP server works with no configuration. For self-hosting or testing you can override:

| Env var | Purpose | Default |
|---|---|---|
| `AFA_BACKEND_URL` | Hosted backend base URL | `https://vooom-agileforagents.hf.space` |
| `AFA_BACKEND_TIMEOUT` | Request timeout (seconds) | `120` |

## Repository layout

| Path | Purpose |
|---|---|
| `src/agileforagents/` | The installable stdio MCP server (thin client + formatters + fallback). |
| `space/` | The Hugging Face Space: FastAPI inference backend + Gradio monitoring dashboard. |
| `tests/` | Unit + E2E tests. |

## Development

```bash
pip install -e ".[dev]"
make format-check && make lint && make typecheck && make test
```

## License

MIT
