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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: context-forge-cli
-Version: 0.2.3
+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.3 → 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.3 → context_forge_cli-0.3.0}/contextforge/adapters/altimate_code.py

@@ -25,6 +25,16 @@ def _count_tokens(text: str) -> int:
         return len(text) // 4
 
 
+def _compute_message_tokens(msg) -> int:
+    """Count tokens across all content: text + tool_call inputs + tool_result outputs."""
+    total = _count_tokens(msg.content)
+    for tc in msg.tool_calls:
+        total += _count_tokens(tc.get("input", ""))
+    for tr in msg.tool_results:
+        total += _count_tokens(tr.get("output", ""))
+    return total
+
+
 class AltimateCodeAdapter(ToolAdapter):
     tool_name = "altimate_code"
     default_paths = [_OPENCODE_DB]
@@ -86,8 +96,6 @@ class AltimateCodeAdapter(ToolAdapter):
             conn = sqlite3.connect(str(_OPENCODE_DB))
             conn.row_factory = sqlite3.Row
             cur = conn.cursor()
-            # Join message + part to get full content
-            # Note: altimate-code stores data as JSON in 'data' column
             cur.execute(
                 """
                 SELECT
@@ -95,7 +103,11 @@ class AltimateCodeAdapter(ToolAdapter):
                     json_extract(m.data, '$.role') as role,
                     m.time_created as ts,
                     json_extract(p.data, '$.type') as part_type,
-                    json_extract(p.data, '$.text') as content
+                    json_extract(p.data, '$.text') as text_content,
+                    json_extract(p.data, '$.tool') as tool_name,
+                    json_extract(p.data, '$.callID') as call_id,
+                    json_extract(p.data, '$.state.input') as tool_input,
+                    json_extract(p.data, '$.state.output') as tool_output
                 FROM message m
                 LEFT JOIN part p ON p.message_id = m.id
                 WHERE m.session_id = ?
@@ -112,24 +124,29 @@ class AltimateCodeAdapter(ToolAdapter):
         current_msg_id: str | None = None
         current_role: str | None = None
         current_parts: list[str] = []
+        current_tool_calls: list[dict] = []
+        current_tool_results: list[dict] = []
         current_ts: datetime | None = None
 
         def flush():
             nonlocal current_msg_id, current_role, current_parts, current_ts
-            if current_role and current_parts:
+            nonlocal current_tool_calls, current_tool_results
+            if current_role and (current_parts or current_tool_calls):
                 content = "\n".join(p for p in current_parts if p)
-                if content:
-                    messages.append(
-                        Message(
-                            role=current_role,
-                            content=content,
-                            timestamp=current_ts,
-                            token_count=_count_tokens(content),
-                        )
-                    )
+                msg = Message(
+                    role=current_role,
+                    content=content,
+                    timestamp=current_ts,
+                    tool_calls=list(current_tool_calls),
+                    tool_results=list(current_tool_results),
+                )
+                msg.token_count = _compute_message_tokens(msg)
+                messages.append(msg)
             current_msg_id = None
             current_role = None
             current_parts = []
+            current_tool_calls = []
+            current_tool_results = []
             current_ts = None
 
         for row in rows:
@@ -138,7 +155,6 @@ class AltimateCodeAdapter(ToolAdapter):
             if role not in ("user", "assistant"):
                 continue
 
-            # Flush when message ID changes (new message in the message table)
             if msg_id != current_msg_id:
                 flush()
                 current_msg_id = msg_id
@@ -149,28 +165,36 @@ class AltimateCodeAdapter(ToolAdapter):
                     current_ts = None
 
             part_type = row["part_type"] or ""
-            content = row["content"] or ""
 
-            if part_type in ("text", "reasoning") and content:
-                if isinstance(content, str):
+            if part_type in ("text", "reasoning"):
+                content = row["text_content"] or ""
+                if isinstance(content, str) and content:
                     try:
                         parsed = json.loads(content)
                         if isinstance(parsed, dict):
                             content = parsed.get("text", str(parsed))
                     except (json.JSONDecodeError, TypeError):
                         pass
-                current_parts.append(str(content).strip())
+                    content = str(content).strip()
+                    if content:
+                        current_parts.append(content)
+
+            elif part_type == "tool":
+                tool_name = row["tool_name"] or "?"
+                tool_input = row["tool_input"] or ""
+                tool_output = row["tool_output"] or ""
+                # input from json_extract is already a JSON string; keep as-is for token counting
+                current_tool_calls.append({"name": tool_name, "input": tool_input})
+                if tool_output:
+                    current_tool_results.append({"output": tool_output})
 
         flush()
         return messages
 
     def _count_session_tokens(self, session_id: str) -> int:
-        """Count total tokens in a session."""
+        """Count total tokens in a session (text + tool inputs + tool outputs)."""
         messages = self.load_messages(session_id)
-        total = 0
-        for msg in messages:
-            total += msg.token_count or _count_tokens(msg.content)
-        return total
+        return sum(msg.token_count or _compute_message_tokens(msg) for msg in messages)
 
     def build_inject_command(
         self,

{context_forge_cli-0.2.3 → context_forge_cli-0.3.0}/contextforge/adapters/claude_code.py

@@ -64,6 +64,16 @@ def _count_tokens(text: str) -> int:
         return len(text) // 4
 
 
+def _compute_message_tokens(msg: Message) -> int:
+    """Count tokens across all content in a message: text + tool_call inputs + tool_result outputs."""
+    total = _count_tokens(msg.content)
+    for tc in msg.tool_calls:
+        total += _count_tokens(tc.get("input", ""))
+    for tr in msg.tool_results:
+        total += _count_tokens(tr.get("output", ""))
+    return total
+
+
 class ClaudeCodeAdapter(ToolAdapter):
     tool_name = "claude_code"
     default_paths = [_HISTORY_PATH, _PROJECTS_DIR]
@@ -309,17 +319,6 @@ class ClaudeCodeAdapter(ToolAdapter):
                 role = msg_data.get("role", entry_type)
                 content_raw = msg_data.get("content", "")
 
-                # Skip entries where content is an array of tool results/tool use
-                # (these are Claude's internal messages, not user input or assistant responses)
-                if isinstance(content_raw, list):
-                    # Only include arrays that contain text blocks (actual assistant content)
-                    if not any(block.get("type") == "text" for block in content_raw if isinstance(block, dict)):
-                        continue
-
-                content = _parse_content(content_raw)
-                if not content:
-                    continue
-
                 ts_str = entry.get("timestamp")
                 ts = None
                 if ts_str:
@@ -328,14 +327,63 @@ class ClaudeCodeAdapter(ToolAdapter):
                     except (ValueError, AttributeError):
                         pass
 
-                messages.append(
-                    Message(
-                        role="user" if role == "user" else "assistant",
-                        content=content,
-                        timestamp=ts,
-                        token_count=_count_tokens(content),
+                if isinstance(content_raw, list):
+                    has_text = any(
+                        isinstance(b, dict) and b.get("type") == "text"
+                        for b in content_raw
                     )
+                    has_tool_result = any(
+                        isinstance(b, dict) and b.get("type") == "tool_result"
+                        for b in content_raw
+                    )
+
+                    # tool_result-only user entries: attribute their outputs to the
+                    # last assistant turn (the one that issued the tool calls)
+                    if has_tool_result and not has_text:
+                        if messages and messages[-1].role == "assistant":
+                            last = messages[-1]
+                            for block in content_raw:
+                                if not isinstance(block, dict) or block.get("type") != "tool_result":
+                                    continue
+                                inner = block.get("content", "")
+                                if isinstance(inner, list):
+                                    for item in inner:
+                                        if isinstance(item, dict) and item.get("type") == "text":
+                                            output = item.get("text", "")
+                                            if output:
+                                                last.tool_results.append({"output": output})
+                                elif isinstance(inner, str) and inner:
+                                    last.tool_results.append({"output": inner})
+                            # Recompute token_count now that tool_results have been added
+                            last.token_count = _compute_message_tokens(last)
+                        continue
+
+                    # Extract tool_call entries from assistant content arrays
+                    tool_calls: list[dict] = []
+                    if role != "user":
+                        for block in content_raw:
+                            if not isinstance(block, dict) or block.get("type") != "tool_use":
+                                continue
+                            try:
+                                input_str = json.dumps(block.get("input", {}))
+                            except (TypeError, ValueError):
+                                input_str = ""
+                            tool_calls.append({"name": block.get("name", "?"), "input": input_str})
+                else:
+                    tool_calls = []
+
+                content = _parse_content(content_raw)
+                if not content and not tool_calls:
+                    continue
+
+                msg = Message(
+                    role="user" if role == "user" else "assistant",
+                    content=content,
+                    timestamp=ts,
+                    tool_calls=tool_calls,
                 )
+                msg.token_count = _compute_message_tokens(msg)
+                messages.append(msg)
 
         return messages
 

{context_forge_cli-0.2.3 → context_forge_cli-0.3.0}/contextforge/adapters/codex.py

@@ -41,6 +41,30 @@ def _count_tokens(text: str) -> int:
         return len(text) // 4
 
 
+def _compute_message_tokens(msg: Message) -> int:
+    total = _count_tokens(msg.content)
+    for tc in msg.tool_calls:
+        total += _count_tokens(tc.get("input", ""))
+    for tr in msg.tool_results:
+        total += _count_tokens(tr.get("output", ""))
+    return total
+
+
+def _extract_function_output(raw_output: str) -> str:
+    """Extract the human-readable output from a Codex function_call_output payload.
+
+    The `output` field is a JSON string: {"output": "...", "metadata": {...}}.
+    Returns the inner "output" string, or the raw string on parse failure.
+    """
+    try:
+        parsed = json.loads(raw_output)
+        if isinstance(parsed, dict):
+            return str(parsed.get("output", raw_output))
+    except (json.JSONDecodeError, TypeError):
+        pass
+    return raw_output
+
+
 class CodexAdapter(ToolAdapter):
     tool_name = "codex"
     default_paths = [_CODEX_DB, _CODEX_SESSIONS_DIR]
@@ -87,7 +111,10 @@ class CodexAdapter(ToolAdapter):
                     cwd=row["cwd"] or None,
                     created_at=created,
                     updated_at=updated,
-                    token_count=row["tokens_used"],
+                    # tokens_used in state_5.sqlite is cumulative API billing spend
+                    # (re-sends full context each call), NOT conversation footprint.
+                    # Leave token_count=None so cf refresh computes it from rollout content.
+                    token_count=None,
                     raw_path=row["rollout_path"] or None,
                     status="unknown",
                 )
@@ -184,6 +211,31 @@ class CodexAdapter(ToolAdapter):
 
     def _parse_rollout(self, path: Path) -> list[Message]:
         messages: list[Message] = []
+
+        # Pending tool data for the current assistant turn (buffered until
+        # we see the agent_message that closes the turn).
+        pending_tool_calls: list[dict] = []
+        pending_tool_results: list[dict] = []
+
+        def flush_pending_assistant(text: str = "", ts=None):
+            """Emit an assistant message with any buffered tool data."""
+            nonlocal pending_tool_calls, pending_tool_results
+            if not text and not pending_tool_calls:
+                pending_tool_calls = []
+                pending_tool_results = []
+                return
+            msg = Message(
+                role="assistant",
+                content=text,
+                timestamp=ts,
+                tool_calls=list(pending_tool_calls),
+                tool_results=list(pending_tool_results),
+            )
+            msg.token_count = _compute_message_tokens(msg)
+            messages.append(msg)
+            pending_tool_calls = []
+            pending_tool_results = []
+
         with path.open() as f:
             for line in f:
                 line = line.strip()
@@ -196,30 +248,42 @@ class CodexAdapter(ToolAdapter):
 
                 entry_type = entry.get("type", "")
                 payload = entry.get("payload", {})
+                ts_str = entry.get("timestamp")
+                ts = None
+                if ts_str:
+                    try:
+                        ts = datetime.fromisoformat(ts_str.replace("Z", "+00:00"))
+                    except (ValueError, AttributeError):
+                        pass
 
                 if entry_type == "event_msg":
                     msg_type = payload.get("type", "")
-                    # user_message / agent_message are the clean human-facing turns.
-                    # response_item entries are skipped — they contain system context
-                    # injections (AGENTS.md, environment_context) and duplicate content.
                     if msg_type == "user_message":
-                        text = payload.get("message", "")
+                        # New user turn — flush any orphaned tool data first
+                        flush_pending_assistant()
+                        text = str(payload.get("message", ""))
                         if text:
-                            text_str = str(text)
-                            messages.append(Message(
-                                role="user",
-                                content=text_str,
-                                token_count=_count_tokens(text_str),
-                            ))
+                            msg = Message(role="user", content=text, timestamp=ts)
+                            msg.token_count = _count_tokens(text)
+                            messages.append(msg)
                     elif msg_type == "agent_message":
-                        text = payload.get("message", "")
-                        if text:
-                            text_str = str(text)
-                            messages.append(Message(
-                                role="assistant",
-                                content=text_str,
-                                token_count=_count_tokens(text_str),
-                            ))
+                        text = str(payload.get("message", ""))
+                        flush_pending_assistant(text=text, ts=ts)
+
+                elif entry_type == "response_item":
+                    item_type = payload.get("type", "")
+                    if item_type == "function_call":
+                        name = payload.get("name", "?")
+                        arguments = payload.get("arguments", "")
+                        pending_tool_calls.append({"name": name, "input": arguments})
+                    elif item_type == "function_call_output":
+                        raw_output = payload.get("output", "")
+                        output = _extract_function_output(raw_output)
+                        if output:
+                            pending_tool_results.append({"output": output})
+
+        # Flush any trailing tool data (e.g. incomplete / aborted turn)
+        flush_pending_assistant()
 
         return messages
 

{context_forge_cli-0.2.3 → 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
 # ---------------------------------------------------------------------------