agentpack-cli 0.1.8__tar.gz → 0.1.9__tar.gz

{agentpack_cli-0.1.8 → agentpack_cli-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentpack-cli
-Version: 0.1.8
+Version: 0.1.9
 Summary: Token-aware context packing for AI coding agents — Claude, Cursor, Windsurf, and Codex
 License: MIT
 License-File: LICENSE
@@ -23,18 +23,13 @@ Requires-Dist: tomli-w>=1.0.0
 Requires-Dist: tomli>=2.0.0; python_version < '3.11'
 Requires-Dist: typer>=0.12.0
 Provides-Extra: all
-Requires-Dist: anthropic>=0.39.0; extra == 'all'
 Requires-Dist: mcp>=1.0.0; extra == 'all'
-Requires-Dist: openai>=1.0.0; extra == 'all'
 Requires-Dist: watchdog>=4.0.0; extra == 'all'
 Provides-Extra: dev
 Requires-Dist: mypy; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
 Requires-Dist: tomli>=2.0.0; (python_version < '3.11') and extra == 'dev'
-Provides-Extra: llm
-Requires-Dist: anthropic>=0.39.0; extra == 'llm'
-Requires-Dist: openai>=1.0.0; extra == 'llm'
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.0.0; extra == 'mcp'
 Provides-Extra: watch
@@ -48,7 +43,7 @@ Description-Content-Type: text/markdown
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml/badge.svg)](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml)
 
-> **Status: alpha (v0.1.5).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Not yet validated across a wide range of repos. API may change before 1.0.
+> **Status: alpha (v0.1.9).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Not yet validated across a wide range of repos. API may change before 1.0.
 >
 > **Platform note:** macOS and Linux are fully supported. Windows support is not yet implemented (git hooks use POSIX shell; the Claude Code session hooks use `python3`/`rm -f`). Contributions welcome.
 
@@ -598,14 +593,14 @@ All installs are idempotent — safe to re-run, merge with existing config, neve
 
 ### `agentpack summarize`
 
-Build or refresh the offline summary cache. **No API calls.**
+Build or refresh the offline summary cache. **No API calls, ever.**
 
 ```bash
 agentpack summarize              # build summaries for all files not yet cached
 agentpack summarize --refresh    # force rebuild all
 ```
 
-Run this once after `init`. After that, pack automatically rebuilds summaries only for changed files.
+Summaries are built with parallel AST/regex analysis — no network, no tokens spent. Run once after `init`. After that, pack automatically rebuilds summaries only for changed files (hash-keyed cache).
 
 ---
 
@@ -635,6 +630,7 @@ Options:
 | `--since` | — | Only include files changed since this git ref |
 | `--session` | off | Re-pack on every file change (watch mode) |
 | `--refresh` | off | Force rebuild summaries before packing |
+| `--budget` | 25000 | Token budget override |
 
 **Budget modes:**
 
@@ -699,6 +695,47 @@ Requires an initialized project (`agentpack init`). Refreshes context, prints th
 
 ---
 
+### `agentpack mcp`
+
+Run AgentPack as an MCP server — exposes context packing as tools that Claude Code (and any MCP-compatible agent) can call directly.
+
+```bash
+pip install "agentpack-cli[mcp]"
+agentpack mcp
+```
+
+Register in Claude Code settings (`~/.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "agentpack": {
+      "command": "agentpack",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+**Tools exposed:**
+
+| Tool | Description |
+|---|---|
+| `pack_context(task, mode, budget, max_tokens)` | Generate a ranked context pack for a task. Returns packed markdown, truncated to `max_tokens` (default 20,000). |
+| `get_context()` | Return the latest pre-built pack instantly (no repack). Prepends a freshness/staleness header so you know if it's stale. |
+| `refresh()` | Refresh using the current `task.md` or git-inferred task. |
+
+**Staleness detection:** `get_context()` compares the snapshot hash from when the pack was built against the current repo snapshot. If files changed since last pack, it prepends:
+```
+> **Stale context** — repo changed since last pack (generated: ...). Run pack_context() to refresh.
+```
+
+**Smart truncation:** `pack_context()` keeps headers intact and trims file content blocks to fit the token budget, appending a note about how many files were omitted.
+
+Zero API calls — all analysis is offline. Summary cache keyed by file hash: cold run parallelises AST parsing across CPU cores; warm cache hits are instant.
+
+---
+
 ### `agentpack explain`
 
 Debug file selection — show which files would be selected, why, and what was excluded — without writing a context pack.
@@ -920,10 +957,6 @@ include_tests = true
 include_configs = true
 include_receipts = true
 
-[summary]
-provider = "offline"
-schema_version = 1
-
 [agents.claude]
 output = ".agentpack/context.claude.md"
 patch_claude_md = true
@@ -1026,7 +1059,6 @@ Works like `.gitignore`. Default rules exclude:
           │  miss → build from AST/regex, cache it  │
           │                                         │
           │  offline  ──  AST / regex extract       │
-          │  claude   ──  Haiku API (optional)      │
           └────────────────────┬────────────────────┘
                                │
           ┌────────────────────▼────────────────────┐
@@ -1127,8 +1159,7 @@ src/agentpack/
 
   summaries/
     offline.py                 # zero-API: AST/regex → imports, symbols, summary
-    llm.py                     # Claude Haiku API summaries (optional)
-    base.py                    # cache-or-build orchestration
+    base.py                    # cache-or-build orchestration (parallel, ThreadPool+ProcessPool)
 
   adapters/                    # context rendering only — no installation logic
     base.py                    # abstract BaseAdapter (output_path + render + write)
@@ -1365,7 +1396,7 @@ config_file     = 60   # was 25 — configs always matter here
 
 ## Principles
 
-- **Local-first**: `init`, `scan`, `diff`, `pack`, `stats`, `summarize` make zero API calls by default
+- **Local-first**: `init`, `scan`, `diff`, `pack`, `stats`, `summarize` make zero API calls — ever. No optional LLM paths, no per-file costs.
 - **Non-destructive**: never overwrites user files; config patching only touches agentpack-managed blocks
 - **Agent-neutral**: architecture is generic; Claude Code is the primary target (deepest integration); Cursor, Windsurf, Codex, and Antigravity are supported but less battle-tested
 - **No daemons**: file watching is opt-in via `agentpack watch`; git hooks run in the background and are opt-in via `install`
@@ -1387,9 +1418,9 @@ config_file     = 60   # was 25 — configs always matter here
 ## Optional dependencies
 
 ```bash
-pip install "agentpack-cli[llm]"      # anthropic — LLM summaries via Claude Haiku
 pip install "agentpack-cli[watch]"    # watchdog — faster file watching for agentpack watch
-pip install "agentpack-cli[all]"      # llm + watch
+pip install "agentpack-cli[mcp]"      # mcp — expose agentpack as MCP server tools
+pip install "agentpack-cli[all]"      # watch + mcp
 ```
 
 ---

{agentpack_cli-0.1.8 → agentpack_cli-0.1.9}/README.md

@@ -5,7 +5,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml/badge.svg)](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml)
 
-> **Status: alpha (v0.1.5).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Not yet validated across a wide range of repos. API may change before 1.0.
+> **Status: alpha (v0.1.9).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Not yet validated across a wide range of repos. API may change before 1.0.
 >
 > **Platform note:** macOS and Linux are fully supported. Windows support is not yet implemented (git hooks use POSIX shell; the Claude Code session hooks use `python3`/`rm -f`). Contributions welcome.
 
@@ -555,14 +555,14 @@ All installs are idempotent — safe to re-run, merge with existing config, neve
 
 ### `agentpack summarize`
 
-Build or refresh the offline summary cache. **No API calls.**
+Build or refresh the offline summary cache. **No API calls, ever.**
 
 ```bash
 agentpack summarize              # build summaries for all files not yet cached
 agentpack summarize --refresh    # force rebuild all
 ```
 
-Run this once after `init`. After that, pack automatically rebuilds summaries only for changed files.
+Summaries are built with parallel AST/regex analysis — no network, no tokens spent. Run once after `init`. After that, pack automatically rebuilds summaries only for changed files (hash-keyed cache).
 
 ---
 
@@ -592,6 +592,7 @@ Options:
 | `--since` | — | Only include files changed since this git ref |
 | `--session` | off | Re-pack on every file change (watch mode) |
 | `--refresh` | off | Force rebuild summaries before packing |
+| `--budget` | 25000 | Token budget override |
 
 **Budget modes:**
 
@@ -656,6 +657,47 @@ Requires an initialized project (`agentpack init`). Refreshes context, prints th
 
 ---
 
+### `agentpack mcp`
+
+Run AgentPack as an MCP server — exposes context packing as tools that Claude Code (and any MCP-compatible agent) can call directly.
+
+```bash
+pip install "agentpack-cli[mcp]"
+agentpack mcp
+```
+
+Register in Claude Code settings (`~/.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "agentpack": {
+      "command": "agentpack",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+**Tools exposed:**
+
+| Tool | Description |
+|---|---|
+| `pack_context(task, mode, budget, max_tokens)` | Generate a ranked context pack for a task. Returns packed markdown, truncated to `max_tokens` (default 20,000). |
+| `get_context()` | Return the latest pre-built pack instantly (no repack). Prepends a freshness/staleness header so you know if it's stale. |
+| `refresh()` | Refresh using the current `task.md` or git-inferred task. |
+
+**Staleness detection:** `get_context()` compares the snapshot hash from when the pack was built against the current repo snapshot. If files changed since last pack, it prepends:
+```
+> **Stale context** — repo changed since last pack (generated: ...). Run pack_context() to refresh.
+```
+
+**Smart truncation:** `pack_context()` keeps headers intact and trims file content blocks to fit the token budget, appending a note about how many files were omitted.
+
+Zero API calls — all analysis is offline. Summary cache keyed by file hash: cold run parallelises AST parsing across CPU cores; warm cache hits are instant.
+
+---
+
 ### `agentpack explain`
 
 Debug file selection — show which files would be selected, why, and what was excluded — without writing a context pack.
@@ -877,10 +919,6 @@ include_tests = true
 include_configs = true
 include_receipts = true
 
-[summary]
-provider = "offline"
-schema_version = 1
-
 [agents.claude]
 output = ".agentpack/context.claude.md"
 patch_claude_md = true
@@ -983,7 +1021,6 @@ Works like `.gitignore`. Default rules exclude:
           │  miss → build from AST/regex, cache it  │
           │                                         │
           │  offline  ──  AST / regex extract       │
-          │  claude   ──  Haiku API (optional)      │
           └────────────────────┬────────────────────┘
                                │
           ┌────────────────────▼────────────────────┐
@@ -1084,8 +1121,7 @@ src/agentpack/
 
   summaries/
     offline.py                 # zero-API: AST/regex → imports, symbols, summary
-    llm.py                     # Claude Haiku API summaries (optional)
-    base.py                    # cache-or-build orchestration
+    base.py                    # cache-or-build orchestration (parallel, ThreadPool+ProcessPool)
 
   adapters/                    # context rendering only — no installation logic
     base.py                    # abstract BaseAdapter (output_path + render + write)
@@ -1322,7 +1358,7 @@ config_file     = 60   # was 25 — configs always matter here
 
 ## Principles
 
-- **Local-first**: `init`, `scan`, `diff`, `pack`, `stats`, `summarize` make zero API calls by default
+- **Local-first**: `init`, `scan`, `diff`, `pack`, `stats`, `summarize` make zero API calls — ever. No optional LLM paths, no per-file costs.
 - **Non-destructive**: never overwrites user files; config patching only touches agentpack-managed blocks
 - **Agent-neutral**: architecture is generic; Claude Code is the primary target (deepest integration); Cursor, Windsurf, Codex, and Antigravity are supported but less battle-tested
 - **No daemons**: file watching is opt-in via `agentpack watch`; git hooks run in the background and are opt-in via `install`
@@ -1344,9 +1380,9 @@ config_file     = 60   # was 25 — configs always matter here
 ## Optional dependencies
 
 ```bash
-pip install "agentpack-cli[llm]"      # anthropic — LLM summaries via Claude Haiku
 pip install "agentpack-cli[watch]"    # watchdog — faster file watching for agentpack watch
-pip install "agentpack-cli[all]"      # llm + watch
+pip install "agentpack-cli[mcp]"      # mcp — expose agentpack as MCP server tools
+pip install "agentpack-cli[all]"      # watch + mcp
 ```
 
 ---

{agentpack_cli-0.1.8 → agentpack_cli-0.1.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentpack-cli"
-version = "0.1.8"
+version = "0.1.9"
 description = "Token-aware context packing for AI coding agents — Claude, Cursor, Windsurf, and Codex"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -31,11 +31,6 @@ dependencies = [
 agentpack = "agentpack.cli:app"
 
 [project.optional-dependencies]
-llm = [
-  "anthropic>=0.39.0",
-  "openai>=1.0.0"
-]
-
 watch = [
   "watchdog>=4.0.0"
 ]
@@ -45,8 +40,6 @@ mcp = [
 ]
 
 all = [
-  "anthropic>=0.39.0",
-  "openai>=1.0.0",
   "watchdog>=4.0.0",
   "mcp>=1.0.0"
 ]
@@ -60,6 +53,9 @@ dev = [
 
 [tool.pytest.ini_options]
 pythonpath = ["src"]
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+]
 
 [build-system]
 requires = ["hatchling"]

{agentpack_cli-0.1.8 → agentpack_cli-0.1.9}/src/agentpack/__init__.py

@@ -1,3 +1,3 @@
 """AgentPack — token-aware context packing for AI coding agents."""
 
-__version__ = "0.1.6"
+__version__ = "0.1.9"

{agentpack_cli-0.1.8 → agentpack_cli-0.1.9}/src/agentpack/application/pack_service.py

@@ -31,7 +31,6 @@ class PackRequest:
     budget: int
     since: str | None
     refresh: bool
-    summary_provider: str
 
 
 @dataclass
@@ -176,7 +175,7 @@ class PackPlanner:
         packable = scan_result.packable
 
         t0 = time.perf_counter()
-        summaries_objs = build_all_summaries(packable, root, request.summary_provider)
+        summaries_objs = build_all_summaries(packable, root)
         summaries = {p: s.model_dump() for p, s in summaries_objs.items()}
         phase_times["summarize"] = time.perf_counter() - t0
 

{agentpack_cli-0.1.8 → agentpack_cli-0.1.9}/src/agentpack/commands/benchmark.py

@@ -152,7 +152,6 @@ def _run_case(root: Path, case: BenchmarkCase) -> CaseResult:
         budget=0,
         since=None,
         refresh=False,
-        summary_provider="offline",
     )
 
     t0 = time.perf_counter()

{agentpack_cli-0.1.8 → agentpack_cli-0.1.9}/src/agentpack/commands/explain.py

@@ -118,7 +118,6 @@ def register(app: typer.Typer) -> None:
         mode: str = typer.Option("balanced", "--mode", help="Budget mode (minimal|balanced|deep)."),
         budget: int = typer.Option(0, "--budget", help="Token budget (0 = use config default)."),
         since: Optional[str] = typer.Option(None, "--since", help="Git ref to compare against (e.g. HEAD~1, main)."),
-        summary_provider: str = typer.Option("offline", "--summary-provider", help="Summary provider (offline|claude)."),
         file: Optional[str] = typer.Option(None, "--file", help="Show detailed score breakdown for a specific file."),
         omitted: bool = typer.Option(False, "--omitted", is_flag=True, help="Show top-10 excluded files and why."),
     ) -> None:
@@ -138,7 +137,6 @@ def register(app: typer.Typer) -> None:
             budget=budget,
             since=since,
             refresh=False,
-            summary_provider=summary_provider,
         )
 
         with console.status("[bold]Planning..."):

{agentpack_cli-0.1.8 → agentpack_cli-0.1.9}/src/agentpack/commands/pack.py

@@ -25,7 +25,6 @@ def register(app: typer.Typer) -> None:
         budget: int = typer.Option(0, "--budget", help="Token budget (0 = use config default)."),
         since: Optional[str] = typer.Option(None, "--since", help="Git ref to compare against (e.g. HEAD~1, main)."),
         refresh: bool = typer.Option(False, "--refresh", help="Rebuild summaries before packing."),
-        summary_provider: str = typer.Option("offline", "--summary-provider", help="Summary provider (offline|claude)."),
         watch: bool = typer.Option(False, "--watch", help="Watch for file changes and re-pack automatically."),
         session: bool = typer.Option(False, "--session", help="Keep re-packing on changes for the whole session (alias for --watch)."),
     ) -> None:
@@ -39,7 +38,7 @@ def register(app: typer.Typer) -> None:
 
         if watch or session:
             _pack_watch(agent=resolved_agent, task=resolved_task, mode=mode, budget=budget,
-                        since=since, summary_provider=summary_provider)
+                        since=since)
             return
 
         result = PackService().run(PackRequest(
@@ -50,7 +49,6 @@ def register(app: typer.Typer) -> None:
             budget=budget,
             since=since,
             refresh=refresh,
-            summary_provider=summary_provider,
         ))
         _print_pack_summary(result)
 
@@ -159,7 +157,6 @@ def _pack_watch(
     mode: str,
     budget: int,
     since: str | None,
-    summary_provider: str,
 ) -> None:
     try:
         from watchdog.observers import Observer
@@ -176,7 +173,7 @@ def _pack_watch(
     def _run_pack() -> None:
         result = PackService().run(PackRequest(
             root=root, agent=agent, task=task, mode=mode, budget=budget,
-            since=since, refresh=False, summary_provider=summary_provider,
+            since=since, refresh=False,
         ))
         _print_pack_summary(result)
 

{agentpack_cli-0.1.8 → agentpack_cli-0.1.9}/src/agentpack/commands/session.py

@@ -177,7 +177,6 @@ def _run_refresh(
             budget=budget,
             since=None,
             refresh=False,
-            summary_provider="offline",
         ))
 
         # Write context files atomically — avoids partial reads if interrupted mid-write

agentpack_cli-0.1.9/src/agentpack/commands/summarize.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import typer
+
+from agentpack.core.config import load_config
+from agentpack.core.ignore import load_spec
+from agentpack.core.scanner import scan
+from agentpack.summaries.base import get_or_build_summary
+from agentpack.commands._shared import console, _root
+
+
+def register(app: typer.Typer) -> None:
+    @app.command()
+    def summarize(
+        refresh: bool = typer.Option(False, "--refresh", help="Force rebuild all summaries."),
+    ) -> None:
+        """Build or refresh offline summary cache (no API calls)."""
+        root = _root()
+        cfg = load_config(root)
+        ignore_spec = load_spec(root / cfg.project.ignore_file)
+
+        console.print("[bold]Building offline summaries...[/]")
+
+        scan_result = scan(root, ignore_spec, cfg.context.max_file_tokens)
+        active = scan_result.packable
+
+        if refresh:
+            from agentpack.core import cache as summary_cache
+            for fi in active:
+                if fi.hash:
+                    cache_path = (
+                        root / ".agentpack" / "cache" /
+                        f"{summary_cache._cache_key(fi.path, fi.hash, 'offline', 1)}.json"
+                    )
+                    cache_path.unlink(missing_ok=True)
+
+        built = 0
+        errors = 0
+        for fi in active:
+            try:
+                get_or_build_summary(fi, root)
+                built += 1
+            except Exception as e:
+                console.print(f"[yellow]Warning:[/] {fi.path}: {e}")
+                errors += 1
+
+        console.print(f"[green]Done.[/] Built/refreshed {built} summaries.", end="")
+        if errors:
+            console.print(f" [yellow]{errors} errors.[/]")
+        else:
+            console.print()

agentpack_cli-0.1.9/src/agentpack/mcp_server.py

@@ -0,0 +1,195 @@
+"""AgentPack MCP server — exposes context packing as MCP tools.
+
+Start with:
+    agentpack mcp
+
+Or register in Claude Code settings:
+    {
+      "mcpServers": {
+        "agentpack": {
+          "command": "agentpack",
+          "args": ["mcp"]
+        }
+      }
+    }
+
+Tools exposed:
+    pack_context   — generate/refresh a context pack for a task
+    get_context    — read the latest context pack (no repack)
+    refresh        — refresh using the current task.md
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+from agentpack.core.token_estimator import estimate_tokens
+
+
+def _repo_root() -> Path:
+    """Walk up from cwd until .agentpack/ found; fall back to cwd."""
+    cwd = Path.cwd()
+    for parent in [cwd, *cwd.parents]:
+        if (parent / ".agentpack").exists():
+            return parent
+    return cwd
+
+
+def _truncate_to_budget(text: str, max_tokens: int = 20000) -> str:
+    """Truncate packed context to fit within max_tokens (estimated via tiktoken, falls back to len//4)."""
+    if estimate_tokens(text) <= max_tokens:
+        return text
+
+    split_marker = "\n## File Context"
+    marker_pos = text.find(split_marker)
+    if marker_pos == -1:
+        budget_chars = max_tokens * 4
+        truncated = text[:budget_chars]
+        omit_files = max(1, (len(text) - budget_chars) // 2000)
+        return truncated + f"\n\n> [Truncated: {omit_files} files omitted to fit context window. Use get_context() to read full pack or narrow the task.]"
+
+    header = text[:marker_pos]
+    file_section = text[marker_pos:]
+
+    if estimate_tokens(header) >= max_tokens:
+        return header + "\n\n> [Truncated: file context omitted to fit context window. Use get_context() to read full pack or narrow the task.]"
+
+    blocks = file_section.split("\n### ")
+    # blocks[0] is the "## File Context" heading; blocks[1:] are individual files
+    accumulated = blocks[0]
+    total_files = len(blocks) - 1
+    kept_files = 0
+    for block in blocks[1:]:
+        candidate = accumulated + "\n### " + block
+        if estimate_tokens(header + candidate) > max_tokens:
+            break
+        accumulated = candidate
+        kept_files += 1
+
+    omitted = total_files - kept_files
+    if omitted > 0:
+        return header + accumulated + f"\n\n> [Truncated: {omitted} files omitted to fit context window. Use get_context() to read full pack or narrow the task.]"
+    return header + accumulated
+
+
+def _get_context_impl(root: Path) -> str:
+    """Read the latest pre-built context pack from root, with staleness header."""
+    pack_path = None
+    for candidate in (
+        root / ".agentpack" / "context.claude.md",
+        root / ".agentpack" / "context.md",
+    ):
+        if candidate.exists():
+            pack_path = candidate
+            break
+    if pack_path is None:
+        return ""
+
+    content = pack_path.read_text(encoding="utf-8")
+
+    metadata_path = root / ".agentpack" / "pack_metadata.json"
+    snapshot_path = root / ".agentpack" / "snapshots" / "latest.json"
+
+    metadata = None
+    if metadata_path.exists():
+        try:
+            metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
+        except Exception:
+            metadata = None
+
+    snapshot = None
+    if snapshot_path.exists():
+        try:
+            snapshot = json.loads(snapshot_path.read_text(encoding="utf-8"))
+        except Exception:
+            snapshot = None
+
+    generated_at = metadata.get("generated_at", "unknown") if metadata else "unknown"
+    token_estimate = metadata.get("token_estimate", 0) if metadata else 0
+
+    if metadata is None or snapshot is None or metadata.get("snapshot_root_hash") != snapshot.get("root_hash"):
+        header = f"> **Stale context** — repo changed since last pack (generated: {generated_at}). Run pack_context() to refresh.\n\n"
+    else:
+        header = f"> Context is fresh (generated: {generated_at}, {token_estimate:,} tokens).\n\n"
+
+    return header + content
+
+
+def serve() -> None:
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except ImportError:
+        print(
+            "mcp package required for MCP server. "
+            "Install: pip install 'agentpack-cli[mcp]'",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    mcp = FastMCP("agentpack")
+
+    @mcp.tool()
+    def pack_context(task: str, mode: str = "balanced", budget: int = 0, max_tokens: int = 20000) -> str:
+        """Generate a ranked context pack for the given task.
+
+        Args:
+            task: Describe what you're working on (e.g. "fix auth token refresh").
+            mode: minimal | balanced (default) | deep
+            budget: Token budget, 0 = config default (usually 25000).
+            max_tokens: Maximum tokens to return (default 20000). Increase for deep context.
+
+        Returns the packed context as a markdown string.
+        """
+        from agentpack.application.pack_service import PackService, PackRequest
+        from agentpack.adapters.detect import detect_agent
+        from agentpack.renderers.markdown import render_claude
+
+        root = _repo_root()
+        agent = detect_agent(root)
+        result = PackService().run(PackRequest(
+            root=root,
+            agent=agent,
+            task=task,
+            mode=mode,
+            budget=budget,
+            since=None,
+            refresh=False,
+        ))
+        return _truncate_to_budget(render_claude(result.pack), max_tokens)
+
+    @mcp.tool()
+    def get_context() -> str:
+        """Return the latest pre-built context pack without repacking.
+
+        Fast — just reads the cached file. Use pack_context() to regenerate.
+        Returns empty string if no pack exists yet.
+        """
+        return _get_context_impl(_repo_root())
+
+    @mcp.tool()
+    def refresh() -> str:
+        """Refresh context using the current task.md (or git-inferred task).
+
+        Equivalent to running `agentpack session refresh`.
+        Returns summary of what was packed.
+        """
+        from agentpack.commands.session import _run_refresh
+        from agentpack.session.state import load_session
+        from agentpack.adapters.detect import detect_agent
+
+        root = _repo_root()
+        state = load_session(root)
+        agent = state.agent if state else detect_agent(root)
+        mode = state.mode if state else "balanced"
+
+        result = _run_refresh(root, agent, mode, 0)
+        if result is None:
+            return "Refresh failed."
+        return (
+            f"Refreshed: {result['files']} files, "
+            f"{result['tokens']:,} tokens, "
+            f"{result['saving']:.1f}% saving"
+        )
+
+    mcp.run()