context-forge-cli 0.2.5__tar.gz → 0.4.0__tar.gz

{context_forge_cli-0.2.5 → context_forge_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: context-forge-cli
-Version: 0.2.5
+Version: 0.4.0
 Summary: Session manager and context bridge for agentic CLI tools
 Project-URL: Homepage, https://github.com/emmver/contextforge
 Project-URL: Repository, https://github.com/emmver/contextforge
@@ -18,6 +18,7 @@ Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Topic :: Utilities
 Requires-Python: >=3.13
 Requires-Dist: anthropic>=0.89.0
+Requires-Dist: mcp>=1.9.0
 Requires-Dist: pydantic>=2.12.5
 Requires-Dist: rich>=14.3.3
 Requires-Dist: sqlite-utils>=3.39
@@ -304,6 +305,111 @@ Press `t` on any session to open the transfer panel. Choose:
 - **Preview** — shows the exact shell command (no side effects)
 - **Execute** — builds the bundle and launches the target tool
 
+## MCP Server
+
+ContextForge ships a [Model Context Protocol](https://modelcontextprotocol.io) server that exposes session data and token analytics to LLM agents.
+
+### Setup
+
+```bash
+# Run directly (after installation)
+cf-mcp
+
+# From source
+uv run python -m contextforge.mcp_server
+```
+
+Register the server with your agentic tool of choice:
+
+#### Claude Code
+
+Add to `~/.claude/claude_desktop_config.json` (global) or `.claude/mcp.json` (project):
+```json
+{
+  "mcpServers": {
+    "contextforge": {
+      "command": "cf-mcp"
+    }
+  }
+}
+```
+
+#### Cursor
+
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
+```json
+{
+  "mcpServers": {
+    "contextforge": {
+      "command": "cf-mcp"
+    }
+  }
+}
+```
+
+Restart Cursor fully after saving.
+
+#### Codex CLI
+
+Add to `~/.codex/config.toml` (global) or `.codex/config.toml` (project):
+```toml
+[mcp_servers.contextforge]
+command = "cf-mcp"
+enabled = true
+```
+
+#### Gemini CLI
+
+Add to `~/.gemini/settings.json` (global) or `.gemini/settings.json` (project):
+```json
+{
+  "mcpServers": {
+    "contextforge": {
+      "command": "cf-mcp"
+    }
+  }
+}
+```
+
+#### Antigravity
+
+Add to `mcp_servers.json` in your project root:
+```json
+{
+  "servers": [
+    {
+      "name": "contextforge",
+      "transport": "stdio",
+      "command": "cf-mcp",
+      "enabled": true
+    }
+  ]
+}
+```
+
+### Tools
+
+| Tool | Description |
+|---|---|
+| `list_sessions` | List indexed sessions; filter by `tool`, limit up to 200 |
+| `get_session` | Full detail for a single session by ID |
+| `get_session_tokens` | Per-turn token breakdown; optionally return only the N heaviest turns |
+| `get_token_analytics` | Aggregated token stats across all sessions for a time window |
+| `get_activity_timeline` | Session count and token usage bucketed over time |
+| `get_top_projects` | Top projects by session count within a time window |
+| `compare_sessions` | Side-by-side token comparison for 2–10 sessions |
+
+All tools are **read-only** and accept a `window` parameter of `7d`, `30d`, `6m`, or `1y` where applicable.
+
+### Example usage
+
+```
+# In Claude Code with the MCP server registered:
+"Show me token usage for all my Claude Code sessions this month"
+"Compare sessions <id1> and <id2> side by side"
+"What are my top 5 projects by session count?"
+```
+
 ## Troubleshooting
 
 ### `command not found: cf`

{context_forge_cli-0.2.5 → context_forge_cli-0.4.0}/README.md

@@ -276,6 +276,111 @@ Press `t` on any session to open the transfer panel. Choose:
 - **Preview** — shows the exact shell command (no side effects)
 - **Execute** — builds the bundle and launches the target tool
 
+## MCP Server
+
+ContextForge ships a [Model Context Protocol](https://modelcontextprotocol.io) server that exposes session data and token analytics to LLM agents.
+
+### Setup
+
+```bash
+# Run directly (after installation)
+cf-mcp
+
+# From source
+uv run python -m contextforge.mcp_server
+```
+
+Register the server with your agentic tool of choice:
+
+#### Claude Code
+
+Add to `~/.claude/claude_desktop_config.json` (global) or `.claude/mcp.json` (project):
+```json
+{
+  "mcpServers": {
+    "contextforge": {
+      "command": "cf-mcp"
+    }
+  }
+}
+```
+
+#### Cursor
+
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
+```json
+{
+  "mcpServers": {
+    "contextforge": {
+      "command": "cf-mcp"
+    }
+  }
+}
+```
+
+Restart Cursor fully after saving.
+
+#### Codex CLI
+
+Add to `~/.codex/config.toml` (global) or `.codex/config.toml` (project):
+```toml
+[mcp_servers.contextforge]
+command = "cf-mcp"
+enabled = true
+```
+
+#### Gemini CLI
+
+Add to `~/.gemini/settings.json` (global) or `.gemini/settings.json` (project):
+```json
+{
+  "mcpServers": {
+    "contextforge": {
+      "command": "cf-mcp"
+    }
+  }
+}
+```
+
+#### Antigravity
+
+Add to `mcp_servers.json` in your project root:
+```json
+{
+  "servers": [
+    {
+      "name": "contextforge",
+      "transport": "stdio",
+      "command": "cf-mcp",
+      "enabled": true
+    }
+  ]
+}
+```
+
+### Tools
+
+| Tool | Description |
+|---|---|
+| `list_sessions` | List indexed sessions; filter by `tool`, limit up to 200 |
+| `get_session` | Full detail for a single session by ID |
+| `get_session_tokens` | Per-turn token breakdown; optionally return only the N heaviest turns |
+| `get_token_analytics` | Aggregated token stats across all sessions for a time window |
+| `get_activity_timeline` | Session count and token usage bucketed over time |
+| `get_top_projects` | Top projects by session count within a time window |
+| `compare_sessions` | Side-by-side token comparison for 2–10 sessions |
+
+All tools are **read-only** and accept a `window` parameter of `7d`, `30d`, `6m`, or `1y` where applicable.
+
+### Example usage
+
+```
+# In Claude Code with the MCP server registered:
+"Show me token usage for all my Claude Code sessions this month"
+"Compare sessions <id1> and <id2> side by side"
+"What are my top 5 projects by session count?"
+```
+
 ## Troubleshooting
 
 ### `command not found: cf`

{context_forge_cli-0.2.5 → context_forge_cli-0.4.0}/contextforge/cli.py

@@ -578,6 +578,31 @@ def refresh(
         )
 
 
+# ---------------------------------------------------------------------------
+# cf mcp
+# ---------------------------------------------------------------------------
+
+@app.command(name="mcp")
+def mcp_server():
+    """Start the ContextForge MCP server (stdio transport).
+
+    Exposes session data and token analysis as MCP tools so LLM agents
+    can query token usage, list sessions, and pull analytics directly.
+
+    Add to your Claude Code MCP config:
+      {
+        "mcpServers": {
+          "contextforge": {
+            "command": "cf",
+            "args": ["mcp"]
+          }
+        }
+      }
+    """
+    from contextforge.mcp_server import main as _run_mcp
+    _run_mcp()
+
+
 # ---------------------------------------------------------------------------
 # cf dashboard
 # ---------------------------------------------------------------------------

{context_forge_cli-0.2.5 → context_forge_cli-0.4.0}/contextforge/core/db.py

@@ -115,14 +115,24 @@ def get_sessions(
     db: sqlite_utils.Database,
     tool: str | None = None,
     limit: int = 200,
+    offset: int = 0,
+    since_ms: int | None = None,
 ) -> list[dict]:
-    where = "tool = ?" if tool else None
-    params = [tool] if tool else []
+    clauses: list[str] = []
+    params: list = []
+    if tool:
+        clauses.append("tool = ?")
+        params.append(tool)
+    if since_ms is not None:
+        clauses.append("updated_at >= ?")
+        params.append(since_ms)
+    where = " AND ".join(clauses) if clauses else None
     rows = db["sessions"].rows_where(
         where,
         params,
         order_by="updated_at desc",
         limit=limit,
+        offset=offset,
     )
     return list(rows)
 

context_forge_cli-0.4.0/contextforge/mcp_server.py

@@ -0,0 +1,307 @@
+"""ContextForge MCP server — exposes token analysis and session tools to LLM agents."""
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from contextforge.core import analytics as analytics_module
+from contextforge.core import db as db_module
+from contextforge.core.token_analyzer import analyze_tokens
+from contextforge.models.config import ForgeConfig
+
+mcp = FastMCP(
+    "contextforge",
+    instructions=(
+        "ContextForge provides read-only access to indexed agentic-tool sessions "
+        "and their token usage. Start with list_sessions to discover what's available "
+        "(supports pagination via offset/limit and date filtering via window). "
+        "Use get_session_tokens for token stats — pass include_turns=True with "
+        "turns_limit/turns_offset to page through per-turn data without blowing up "
+        "the context window. Use get_token_analytics for aggregated stats across all tools."
+    ),
+)
+
+_VALID_WINDOWS = {"7d", "30d", "6m", "1y"}
+
+
+def _db():
+    cfg = ForgeConfig()
+    return db_module.get_db(cfg.db_path)
+
+
+def _short_cwd(cwd: str) -> str:
+    """Return a short project label from a full cwd path.
+
+    Returns the last path component, or '~' for the user home directory,
+    or '' for empty paths.
+    """
+    if not cwd:
+        return ""
+    parts = [p for p in cwd.replace("\\", "/").split("/") if p]
+    if not parts:
+        return ""
+    # Detect home directory: last part is a username-like segment with no parent project
+    # If the path ends at /Users/<name> or /home/<name>, show '~'
+    if len(parts) >= 2 and parts[-2] in ("Users", "home"):
+        return "~"
+    return parts[-1]
+
+
+def _validate_window(window: str) -> str:
+    if window not in _VALID_WINDOWS:
+        raise ValueError(
+            f"Invalid window {window!r}. Must be one of: {', '.join(sorted(_VALID_WINDOWS))}"
+        )
+    return window
+
+
+@mcp.tool()
+def list_sessions(
+    tool: str | None = None,
+    limit: int = 50,
+    offset: int = 0,
+    window: str | None = None,
+) -> list[dict[str, Any]]:
+    """List indexed sessions with basic token summaries.
+
+    Supports pagination via offset/limit and optional date filtering via window.
+
+    Args:
+        tool: Filter by tool name (claude_code, codex, gemini, etc.). Omit for all tools.
+        limit: Page size (default 50, max 200).
+        offset: Number of sessions to skip for pagination (default 0).
+        window: Optional time window to filter by recency — one of "7d", "30d", "6m", "1y".
+    """
+    since_ms: int | None = None
+    if window is not None:
+        _validate_window(window)
+        since_ms = analytics_module._window_start_ms(window)
+
+    db = _db()
+    rows = db_module.get_sessions(
+        db, tool=tool, limit=min(limit, 200), offset=offset, since_ms=since_ms
+    )
+    return [
+        {
+            "id": r["id"],
+            "tool": r["tool"],
+            "title": (r.get("title") or "")[:100],
+            "cwd": _short_cwd(r.get("cwd") or ""),
+            "token_count": r.get("token_count") or 0,
+            "updated_at": r.get("updated_at"),
+            "status": r.get("status") or "",
+        }
+        for r in rows
+    ]
+
+
+@mcp.tool()
+def get_session(session_id: str) -> dict[str, Any] | None:
+    """Get details for a single session by ID.
+
+    Args:
+        session_id: The exact session ID from list_sessions.
+    """
+    db = _db()
+    row = db_module.get_session(db, session_id)
+    if row is None:
+        return None
+    return {
+        "id": row["id"],
+        "tool": row["tool"],
+        "title": (row.get("title") or "")[:100],
+        "cwd": row.get("cwd") or "",
+        "project": _short_cwd(row.get("cwd") or ""),
+        "token_count": row.get("token_count") or 0,
+        "status": row.get("status") or "",
+        "summary": (row.get("summary") or "")[:300],
+        "created_at": row.get("created_at"),
+        "updated_at": row.get("updated_at"),
+        "tags": row.get("tags") or "[]",
+    }
+
+
+@mcp.tool()
+def get_session_tokens(
+    session_id: str,
+    include_turns: bool = False,
+    turns_limit: int = 100,
+    turns_offset: int = 0,
+    top: int = 0,
+) -> dict[str, Any] | None:
+    """Get token breakdown for a session.
+
+    By default returns only summary statistics (cheap). Set include_turns=True
+    to also page through per-turn data using turns_limit and turns_offset.
+
+    Args:
+        session_id: The session ID.
+        include_turns: If True, include per-turn token counts. Default False.
+        turns_limit: Max turns to return per page when include_turns=True (default 100).
+        turns_offset: Turn index to start from for pagination (default 0).
+        top: If > 0, return the N heaviest turns instead of sequential pagination.
+            Overrides turns_offset when set.
+    """
+    db = _db()
+    report = analyze_tokens(db, session_id)
+    if report is None:
+        return None
+
+    result: dict[str, Any] = {
+        "session_id": report.session_id,
+        "tool": report.tool,
+        "title": report.title[:100],
+        "total_tokens": report.total,
+        "user_tokens": report.user_total,
+        "assistant_tokens": report.assistant_total,
+        "tool_call_tokens": report.tool_call_total,
+        "tool_result_tokens": report.tool_result_total,
+        "turn_count": report.turn_count,
+        "avg_user_tokens": round(report.avg_user, 1),
+        "avg_assistant_tokens": round(report.avg_assistant, 1),
+        "has_tool_data": report.has_tool_data,
+        "heaviest_turn": (
+            {
+                "turn": report.max_turn.turn,
+                "role": report.max_turn.role,
+                "tokens": report.max_turn.tokens,
+            }
+            if report.max_turn
+            else None
+        ),
+    }
+
+    if include_turns:
+        turns = report.turns
+        if top > 0:
+            turns = sorted(turns, key=lambda t: t.tokens, reverse=True)[:top]
+            turns = sorted(turns, key=lambda t: t.turn)
+        else:
+            turns = turns[turns_offset: turns_offset + turns_limit]
+        result["turns"] = [
+            {
+                "turn": t.turn,
+                "role": t.role,
+                "tokens": t.tokens,
+                "text_tokens": t.text_tokens,
+                "tool_call_tokens": t.tool_call_tokens,
+                "tool_result_tokens": t.tool_result_tokens,
+            }
+            for t in turns
+        ]
+        if top > 0:
+            result["turns_pagination"] = {
+                "mode": "top",
+                "n": top,
+                "total": report.turn_count,
+            }
+        else:
+            result["turns_pagination"] = {
+                "mode": "sequential",
+                "offset": turns_offset,
+                "limit": turns_limit,
+                "total": report.turn_count,
+                "has_more": (turns_offset + turns_limit) < report.turn_count,
+            }
+
+    return result
+
+
+@mcp.tool()
+def get_token_analytics(window: str = "30d") -> dict[str, Any]:
+    """Get aggregated token usage statistics across all sessions.
+
+    Args:
+        window: Time window — one of "7d", "30d", "6m", "1y" (default "30d").
+    """
+    _validate_window(window)
+    db = _db()
+    overview = analytics_module.get_overview(db, window=window)
+    return {
+        "window": window,
+        "total_sessions": overview.total_sessions,
+        "total_tokens": overview.total_tokens,
+        "active_tools": overview.active_tools,
+        "session_count_by_tool": overview.session_count_by_tool,
+        "token_sum_by_tool": overview.token_sum_by_tool,
+        "date_range": {
+            "start": overview.date_range[0].isoformat() if overview.date_range else None,
+            "end": overview.date_range[1].isoformat() if overview.date_range else None,
+        },
+    }
+
+
+@mcp.tool()
+def get_activity_timeline(window: str = "30d") -> list[dict[str, Any]]:
+    """Get session count and token usage bucketed over time.
+
+    Returns one bucket per day (7d/30d), per week (6m), or per month (1y).
+
+    Args:
+        window: Time window — one of "7d", "30d", "6m", "1y" (default "30d").
+    """
+    _validate_window(window)
+    db = _db()
+    buckets = analytics_module.get_activity_over_time(db, window=window)
+    return [
+        {"label": b.label, "sessions": b.count, "tokens": b.tokens}
+        for b in buckets
+    ]
+
+
+@mcp.tool()
+def get_top_projects(window: str = "30d", top_n: int = 5) -> list[dict[str, Any]]:
+    """Get top projects by session count within a time window.
+
+    Args:
+        window: Time window — one of "7d", "30d", "6m", "1y" (default "30d").
+        top_n: Number of top projects to return (default 5).
+    """
+    _validate_window(window)
+    db = _db()
+    projects = analytics_module.get_top_projects(db, window=window, top_n=top_n)
+    return [{"project": p.project, "session_count": p.count} for p in projects]
+
+
+@mcp.tool()
+def compare_sessions(session_ids: list[str]) -> list[dict[str, Any]]:
+    """Compare token usage across multiple sessions side-by-side.
+
+    Returns one entry per session with key metrics, sorted by total tokens descending.
+
+    Args:
+        session_ids: List of session IDs to compare.
+    """
+    db = _db()
+    results: list[dict[str, Any]] = []
+    for sid in session_ids:
+        report = analyze_tokens(db, sid)
+        if report is None:
+            results.append({"session_id": sid, "error": "not found"})
+            continue
+        results.append({
+            "session_id": sid,
+            "tool": report.tool,
+            "title": report.title[:100],
+            "total_tokens": report.total,
+            "turn_count": report.turn_count,
+            "user_tokens": report.user_total,
+            "assistant_tokens": report.assistant_total,
+            "tool_call_tokens": report.tool_call_total,
+            "tool_result_tokens": report.tool_result_total,
+            "avg_tokens_per_turn": (
+                round(report.total / report.turn_count, 1) if report.turn_count else 0
+            ),
+            "heaviest_turn_tokens": report.max_turn.tokens if report.max_turn else 0,
+        })
+    results.sort(key=lambda r: r.get("total_tokens", 0), reverse=True)
+    return results
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

context_forge_cli-0.4.0/contextforge/utils/tokens.py

@@ -0,0 +1,25 @@
+"""Token counting utilities using tiktoken."""
+from __future__ import annotations
+
+import tiktoken
+
+_ENCODING = None
+
+
+def _get_encoding() -> tiktoken.Encoding:
+    global _ENCODING
+    if _ENCODING is None:
+        _ENCODING = tiktoken.get_encoding("cl100k_base")
+    return _ENCODING
+
+
+def count_tokens(text: str) -> int:
+    return len(_get_encoding().encode(text))
+
+
+def truncate_to_budget(text: str, budget: int) -> str:
+    enc = _get_encoding()
+    tokens = enc.encode(text)
+    if len(tokens) <= budget:
+        return text
+    return enc.decode(tokens[:budget])

{context_forge_cli-0.2.5 → context_forge_cli-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "context-forge-cli"
-version = "0.2.5"
+version = "0.4.0"
 description = "Session manager and context bridge for agentic CLI tools"
 readme = "README.md"
 license = { text = "MIT" }
@@ -21,6 +21,7 @@ classifiers = [
 requires-python = ">=3.13"
 dependencies = [
     "anthropic>=0.89.0",
+    "mcp>=1.9.0",
     "pydantic>=2.12.5",
     "rich>=14.3.3",
     "sqlite-utils>=3.39",
@@ -36,6 +37,7 @@ Repository = "https://github.com/emmver/contextforge"
 
 [project.scripts]
 cf = "contextforge.cli:app"
+cf-mcp = "contextforge.mcp_server:main"
 
 [build-system]
 requires = ["hatchling"]

context_forge_cli-0.4.0/tests/conftest.py

@@ -0,0 +1,32 @@
+"""Shared pytest fixtures — mocks tiktoken for offline test environments."""
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+class _FakeEncoding:
+    """Minimal tiktoken encoding stand-in using word-count approximation."""
+
+    def encode(self, text: str) -> list[int]:
+        return list(range(max(1, len(text.split()))))
+
+    def decode(self, tokens: list[int]) -> str:
+        # Best-effort: can't reconstruct text, but truncate_to_budget tests
+        # only need a shorter string back.
+        return " ".join(["x"] * len(tokens))
+
+
+_FAKE_ENCODING = _FakeEncoding()
+
+
+@pytest.fixture(autouse=True)
+def mock_tiktoken():
+    """Prevent tiktoken from downloading its BPE vocab file over the network.
+
+    Patches _get_encoding() at the source so every importer of count_tokens
+    gets the stub regardless of how they bound the function.
+    """
+    with patch("contextforge.utils.tokens._get_encoding", return_value=_FAKE_ENCODING):
+        yield