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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: context-forge-cli
-Version: 0.2.5
+Version: 0.3.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.3.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.3.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.3.0/contextforge/mcp_server.py

@@ -0,0 +1,219 @@
+"""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, "
+        "then use get_session_tokens for per-turn breakdown or get_token_analytics "
+        "for aggregated stats across all tools."
+    ),
+)
+
+
+def _db():
+    cfg = ForgeConfig()
+    return db_module.get_db(cfg.db_path)
+
+
+@mcp.tool()
+def list_sessions(tool: str | None = None, limit: int = 50) -> list[dict[str, Any]]:
+    """List indexed sessions with basic token summaries.
+
+    Args:
+        tool: Filter by tool name (claude_code, codex, gemini, etc.). Omit for all tools.
+        limit: Maximum sessions to return (default 50, max 200).
+    """
+    db = _db()
+    rows = db_module.get_sessions(db, tool=tool, limit=min(limit, 200))
+    return [
+        {
+            "id": r["id"],
+            "tool": r["tool"],
+            "title": r.get("title") or "",
+            "cwd": r.get("cwd") or "",
+            "token_count": r.get("token_count") or 0,
+            "updated_at": r.get("updated_at"),
+            "status": r.get("status") or "",
+            "summary": r.get("summary") or "",
+        }
+        for r in rows
+    ]
+
+
+@mcp.tool()
+def get_session(session_id: str) -> dict[str, Any] | None:
+    """Get full 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)
+    return dict(row) if row else None
+
+
+@mcp.tool()
+def get_session_tokens(session_id: str, top: int = 0) -> dict[str, Any] | None:
+    """Get per-turn token breakdown for a session.
+
+    Returns total tokens, per-role totals and averages, and a list of turns
+    with individual counts for text, tool calls, and tool results.
+
+    Args:
+        session_id: The session ID.
+        top: If > 0, return only the N heaviest turns (sorted by turn number).
+    """
+    db = _db()
+    report = analyze_tokens(db, session_id)
+    if report is None:
+        return None
+
+    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)
+
+    return {
+        "session_id": report.session_id,
+        "tool": report.tool,
+        "title": report.title,
+        "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,
+                "preview": report.max_turn.content_preview,
+            }
+            if report.max_turn
+            else None
+        ),
+        "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,
+                "cumulative": t.cumulative,
+                "preview": t.content_preview,
+            }
+            for t in turns
+        ],
+    }
+
+
+@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").
+    """
+    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").
+    """
+    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).
+    """
+    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 (2–10 sessions recommended).
+    """
+    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,
+            "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.3.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.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "context-forge-cli"
-version = "0.2.5"
+version = "0.3.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.3.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