d31a81ef3f
## Summary - On every CLI command invocation (except `update`/`upgrade`/`mcp`), a detached subprocess checks PyPI for newer versions (throttled to once per 4 hours) and caches the result at `~/.arcade/update_cache.json` - On the next invocation, if a newer version is known, a yellow one-liner notification is printed suggesting `arcade update` - Respects `ARCADE_DISABLE_AUTOUPDATE=1` environment variable to opt out entirely <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Medium Risk** > Adds a background PyPI version check that spawns detached subprocesses and may print update notifications on most CLI invocations; mistakes could impact CLI reliability or corrupt MCP stdio output (mitigated by explicit command exclusions). > > **Overview** > Adds `arcade update` (and hidden `arcade upgrade` alias) to self-upgrade the `arcade-mcp` CLI by detecting the original install method (`uv tool`, `pipx`, `uv pip`, or `pip`) and running the appropriate upgrade command. > > Introduces a **throttled background update check** on most CLI invocations: a detached subprocess queries PyPI, writes `~/.arcade/update_cache.json`, and on subsequent runs prints a one-line notification when a newer version is cached; this is disabled via `ARCADE_DISABLE_AUTOUPDATE=1` and explicitly skipped for `update`/`upgrade`/`mcp` to avoid MCP stdio output corruption. > > Bumps the package version to `1.13.0`, adds a `packaging` dependency, and includes comprehensive tests covering PyPI/yanked/prerelease handling, install-method detection, caching, and callback integration. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 2d9646ecc2211e8cfecd6e4901d14b1f5b7bb306. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY --> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
77 lines
3.4 KiB
Markdown
77 lines
3.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## What This Is
|
|
|
|
Arcade MCP is a Python tool-calling platform for building MCP (Model Context Protocol) servers. It's a monorepo containing 5 interdependent libraries and a CLI.
|
|
|
|
## Commands
|
|
|
|
| Task | Command |
|
|
|------|---------|
|
|
| Install all packages | `make install` (runs `uv sync --extra all --extra dev`) |
|
|
| Run all lib tests | `make test` |
|
|
| Run a single test | `uv run pytest libs/tests/core/test_toolkit.py::TestClass::test_method` |
|
|
| Lint + type check | `make check` (pre-commit + mypy) |
|
|
| Build all wheels | `make build` |
|
|
|
|
Package manager is **uv** — always use `uv run` to execute Python commands, never bare `pip` or `python`. Python 3.10+. Build system is Hatchling.
|
|
|
|
## Library Dependency Graph
|
|
|
|
```
|
|
arcade-core (base: config, errors, catalog, telemetry)
|
|
├── arcade-tdk (tool decorators, auth providers, annotations)
|
|
├── arcade-serve (FastAPI worker infrastructure, MCP server)
|
|
│ └── arcade-mcp-server (MCPApp class, FastAPI-like interface)
|
|
│ └── arcade-mcp CLI (depends on all above)
|
|
└── arcade-evals (evaluation framework, critics, test suites)
|
|
```
|
|
|
|
## Versioning Rules
|
|
|
|
- Use semver. Bump the version in `pyproject.toml` when modifying a library's code — but first check `git diff main` to see if the version has already been bumped in the current branch. Only bump once per branch/PR.
|
|
- ALWAYS bump the minimum required dependency version when making breaking changes between libraries.
|
|
|
|
## Key Patterns
|
|
|
|
### MCP Server (arcade-mcp-server)
|
|
|
|
```python
|
|
from typing import Annotated
|
|
|
|
from arcade_mcp_server import MCPApp
|
|
|
|
app = MCPApp(name="my_server", version="1.0.0")
|
|
|
|
@app.tool
|
|
def greet(name: Annotated[str, "The name of the person to greet"]) -> str:
|
|
"""Greet a person."""
|
|
return f"Hello, {name}!"
|
|
|
|
if __name__ == "__main__":
|
|
transport = sys.argv[1] if len(sys.argv) > 1 else "stdio"
|
|
app.run(transport=transport, host="127.0.0.1", port=8000)
|
|
```
|
|
|
|
Transports: `stdio` (default) and `http` (tools that require auth or secrets need resource server auth provided by arcade-mcp-server)
|
|
|
|
## Project Layout
|
|
|
|
- `libs/arcade-*/` — Core libraries. Most have their own `pyproject.toml`. libs/arcade-cli and arcade-evals use the top-level `pyproject.toml`.
|
|
- `libs/tests/` — All library tests, grouped by component (core, cli, arcade_mcp_server, tool, sdk, worker)
|
|
- `examples/mcp_servers/` — Example MCP server implementations
|
|
|
|
## Development Rules
|
|
|
|
- **All changes must have tests and follow TDD.** Every new feature, bug fix, or behavioral change needs a corresponding test in `libs/tests/`.
|
|
- **Always use uv.** Never use `pip`, `pip install`, `python`, or `python -m` directly. Use `uv run`, `uv sync`, `uv build`, etc.
|
|
- **Never pollute stdout/stderr in MCP stdio paths.** Code reachable by `arcade-mcp-server` or the `arcade mcp` CLI command must never print, log to stdout, or spawn processes that write to stdout/stderr. The MCP stdio transport requires a clean JSON-only channel — any stray output corrupts the protocol. When adding CLI-wide hooks or notifications, always gate them to exclude MCP transport paths.
|
|
|
|
## Code Quality
|
|
|
|
- **ruff** for linting/formatting
|
|
- **mypy** with strict settings (`disallow_untyped_defs`, `disallow_any_unimported`)
|
|
- **pre-commit** hooks run automatically
|
|
- CI tests on Python 3.10, 3.11, 3.12 across Ubuntu/Windows/macOS
|