context-forge-cli 0.2.3__py3-none-any.whl → 0.3.0__py3-none-any.whl

{context_forge_cli-0.2.3.dist-info → context_forge_cli-0.3.0.dist-info}/METADATA

@@ -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.dist-info → context_forge_cli-0.3.0.dist-info}/RECORD

@@ -1,11 +1,12 @@
 contextforge/__init__.py,sha256=L5NnW7jpnDQrAhnqTWSzW-bk2Bp8TXpFK1-SmQXI2QE,104
-contextforge/cli.py,sha256=cgCWfhXMdOdseiNk5hbd_jlTxQfLLY3y8JUDTqwE2rM,21393
+contextforge/cli.py,sha256=EMUHOpLqrW7pkgpmB_H6WQ7smRFZNnSMno2lEoQecGQ,22075
+contextforge/mcp_server.py,sha256=HVXPjVuY1g2BT4LutHWcPcdSb-_P8TTSK-l5rzR7C3w,7267
 contextforge/adapters/__init__.py,sha256=HGIFdC_tNpX_QOPrePwU5cEVBhp3Hsh6Sihwb23HdTk,171
-contextforge/adapters/altimate_code.py,sha256=YOPtPAWXJgbBMnujHR_ho9pWNNakKqaOQSuKziEpdWc,6577
+contextforge/adapters/altimate_code.py,sha256=1-Cn12pnJixopAXvUoRGOiyn0xy5TJzuwO3Ux1YlNHs,7857
 contextforge/adapters/base.py,sha256=DeB_Yf0NNbdDLrJgVD3bDubW6S9x6O3b8EuYz4y-9m8,1983
-contextforge/adapters/claude_code.py,sha256=lTeGGYlQkEayJAaeeJfddWaktAbe0k3sW2iYqW8iTpk,14671
+contextforge/adapters/claude_code.py,sha256=g2C_aIrLBuQyLeUwI1ddiCmBGN0CEioF6zdypf4dcV8,17156
 contextforge/adapters/claude_desktop.py,sha256=P0fI3Tg00bX8MifV09I1iRPqk-6m5w1kpllCW7Bc2hg,12238
-contextforge/adapters/codex.py,sha256=yj0Sdzo8yrkQHSqfCxq-NxXuaiaUOSlnZOTIAOQw-gU,8776
+contextforge/adapters/codex.py,sha256=KTh4r9TnFvCUHeMl3aLc1bv6pGq1OQwxf22rM8tTGWs,11403
 contextforge/adapters/gemini.py,sha256=757prqt5_AILxFm53CEfhlqjFKlxVs-YmLBImt8Aj1M,6844
 contextforge/adapters/registry.py,sha256=kbasRJE4WBJ8qw7VGENgjp8NDS3jyIHo8wpGxjk9srs,1177
 contextforge/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -15,10 +16,10 @@ contextforge/core/db.py,sha256=1d8HQZEwiEvotByCWWgDyOPJT744lh6vb77XURjscco,5205
 contextforge/core/injector.py,sha256=_4UeJn-hJfs2-cZcqScpJjEBZCOnKc7odcKDYZTj55I,2670
 contextforge/core/scanner.py,sha256=Wbgp4TJ7SmFf-f6ZY6aKlmL_wUTUCFhuMTEjYYPPUhQ,2487
 contextforge/core/summarizer.py,sha256=4qPzBHfLno1C_nyiTGM_It_0vm3alcsYCZKueMQITlA,4631
-contextforge/core/token_analyzer.py,sha256=HKktdSye1Jy8XJ_LktLfVBg2ElYTsaEy9mZb_1vDnTw,2398
+contextforge/core/token_analyzer.py,sha256=78sgW3lhXcB49n1SEk2dn_qn7dqDIlAlRDzDWimqBdo,3288
 contextforge/models/__init__.py,sha256=abmJPhl_AVrhA526IYpF7NqWTy8MBH5jVSAxwOLzuL4,151
 contextforge/models/config.py,sha256=TbqPaOV_oF3kvVFJDGIADRuJid-9UsGq2QQyb8BP_-g,953
-contextforge/models/session.py,sha256=Q3bT3j6r4LdKgV0Yq7DH1RUJPIu1KF6cyJG3iR7qPss,878
+contextforge/models/session.py,sha256=yPndNVzwkW-3mYGTR9ruB-7uKuQnYMO0qi5--nTiqQk,1097
 contextforge/tui/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 contextforge/tui/app.py,sha256=-3ETEJjXAsigVvvB65wpXMBt4L4NiqM4Nj8cS1dBFQ8,7774
 contextforge/tui/styles.tcss,sha256=hiSe3g2OJFME8QAHVHbtvgaB8_BNYfwKvQUmZzbWHHc,945
@@ -27,12 +28,12 @@ contextforge/tui/widgets/session_detail.py,sha256=xjnbD67Es7du7S3q960rZR31erwkNj
 contextforge/tui/widgets/session_table.py,sha256=s-E1j629eY5MgO3IaxOWs03YP6oToaLBXur27h4EV80,9782
 contextforge/tui/widgets/stats_panel.py,sha256=N5rPdrI0_JNsJaggZ30y6eVNGX_eRbHVT40dOm61FiY,12277
 contextforge/tui/widgets/status_bar.py,sha256=uAtgZWA8ah8CynoaEgKqhGYH7MHq6Ih-Nw3_go3-Dkg,3068
-contextforge/tui/widgets/tokens_panel.py,sha256=xsLB-by3ta1zKts9lGSUConAKMHcpVDOyq6BD-utTQk,4669
+contextforge/tui/widgets/tokens_panel.py,sha256=PHuwZV8jNYOHkvHzXR4YG-cevkMuNQ9SHASQWJ9JUfU,10661
 contextforge/tui/widgets/transfer_panel.py,sha256=Qrgkt1-MpzRHWuwNyu2ErM26IRl0yaAMdbx3XMS7Lqk,4145
 contextforge/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 contextforge/utils/display.py,sha256=bagZgpZ6WGki2THNHA8lfg9ITqM8W0q_M6Os-pgwFHk,3111
-contextforge/utils/tokens.py,sha256=UVGz-vvmCIxMgnRPn1T53v2ZdKMmxKhoJcc1qbmjpDQ,414
-context_forge_cli-0.2.3.dist-info/METADATA,sha256=tfspqjUX_n4dERdy1eaMdskkUY0HGEwiN3p8hlzz4gU,12831
-context_forge_cli-0.2.3.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-context_forge_cli-0.2.3.dist-info/entry_points.txt,sha256=nPN0PWb85KCPXqFp4opmBsNejdCHyl7rK_cREsu4r7A,44
-context_forge_cli-0.2.3.dist-info/RECORD,,
+contextforge/utils/tokens.py,sha256=u2QzgkcmVX-PEj5j3_0BdUqFuQB1OABBkaNK02vX9gk,571
+context_forge_cli-0.3.0.dist-info/METADATA,sha256=_ibNpcFhBKcIM9ibjQbQEBH0L5yuvrX-ZJkHRklZAjo,15129
+context_forge_cli-0.3.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+context_forge_cli-0.3.0.dist-info/entry_points.txt,sha256=u_-APOF7WFMcw-CJAbhkPCADmZu-J2fTg80_iqBlOyU,82
+context_forge_cli-0.3.0.dist-info/RECORD,,

{context_forge_cli-0.2.3.dist-info → context_forge_cli-0.3.0.dist-info}/entry_points.txt

@@ -1,2 +1,3 @@
 [console_scripts]
 cf = contextforge.cli:app
+cf-mcp = contextforge.mcp_server:main

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,

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
 

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
 

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
 # ---------------------------------------------------------------------------

contextforge/core/token_analyzer.py

@@ -18,6 +18,9 @@ class TurnStats:
     tokens: int
     content_preview: str  # first 80 chars, single line
     cumulative: int = 0
+    text_tokens: int = 0
+    tool_call_tokens: int = 0
+    tool_result_tokens: int = 0
 
 
 @dataclass
@@ -26,11 +29,20 @@ class SessionTokenReport:
     tool: str
     title: str
     turns: list[TurnStats] = field(default_factory=list)
+    has_tool_data: bool = False
 
     @property
     def total(self) -> int:
         return sum(t.tokens for t in self.turns)
 
+    @property
+    def tool_call_total(self) -> int:
+        return sum(t.tool_call_tokens for t in self.turns)
+
+    @property
+    def tool_result_total(self) -> int:
+        return sum(t.tool_result_tokens for t in self.turns)
+
     @property
     def user_total(self) -> int:
         return sum(t.tokens for t in self.turns if t.role == "user")
@@ -71,8 +83,14 @@ def analyze_tokens(
 
     turns: list[TurnStats] = []
     cumulative = 0
+    has_tool_data = False
     for i, msg in enumerate(messages, 1):
-        tokens = count_tokens(msg.content)
+        text_tokens = count_tokens(msg.content)
+        tool_call_tokens = sum(count_tokens(tc.get("input", "")) for tc in msg.tool_calls)
+        tool_result_tokens = sum(count_tokens(tr.get("output", "")) for tr in msg.tool_results)
+        tokens = text_tokens + tool_call_tokens + tool_result_tokens
+        if tool_call_tokens or tool_result_tokens:
+            has_tool_data = True
         cumulative += tokens
         preview = msg.content.replace("\n", " ").strip()[:80]
         turns.append(TurnStats(
@@ -81,6 +99,9 @@ def analyze_tokens(
             tokens=tokens,
             content_preview=preview,
             cumulative=cumulative,
+            text_tokens=text_tokens,
+            tool_call_tokens=tool_call_tokens,
+            tool_result_tokens=tool_result_tokens,
         ))
 
     return SessionTokenReport(
@@ -88,4 +109,5 @@ def analyze_tokens(
         tool=row["tool"],
         title=row.get("title") or session_id[:16],
         turns=turns,
+        has_tool_data=has_tool_data,
     )

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()

contextforge/models/session.py

@@ -11,6 +11,8 @@ class Message(BaseModel):
     content: str
     timestamp: datetime | None = None
     token_count: int | None = None
+    tool_calls: list[dict] = Field(default_factory=list)  # [{name, input}] on assistant turns
+    tool_results: list[dict] = Field(default_factory=list)  # [{output}] attributed to the assistant turn that invoked them
 
 
 class Session(BaseModel):

contextforge/tui/widgets/tokens_panel.py

@@ -1,13 +1,127 @@
 """TokensPanel — modal screen showing per-turn token analysis for a session."""
 from __future__ import annotations
 
+import json
 from pathlib import Path
 
 from textual.app import ComposeResult
 from textual.binding import Binding
-from textual.containers import Vertical
+from textual.containers import ScrollableContainer, Vertical
 from textual.screen import ModalScreen
-from textual.widgets import DataTable, Footer, Static
+from textual.widgets import DataTable, Static
+
+from contextforge.models.session import Message
+
+
+class TurnDetailPanel(ModalScreen):
+    """Modal showing the full content of a single turn."""
+
+    BINDINGS = [
+        Binding("escape,q", "dismiss(None)", "Close"),
+    ]
+
+    DEFAULT_CSS = """
+    TurnDetailPanel {
+        align: center middle;
+    }
+    TurnDetailPanel > Vertical {
+        width: 92%;
+        height: 88%;
+        border: thick $accent;
+        background: $surface;
+        padding: 0 1;
+    }
+    TurnDetailPanel #turn-header {
+        height: auto;
+        padding: 1 1 0 1;
+        border-bottom: solid $primary-background-lighten-1;
+        margin-bottom: 1;
+    }
+    TurnDetailPanel ScrollableContainer {
+        height: 1fr;
+        padding: 0 1;
+    }
+    TurnDetailPanel .section-label {
+        color: $text-muted;
+        text-style: bold;
+        margin-top: 1;
+    }
+    TurnDetailPanel .content-block {
+        color: $text;
+        margin-bottom: 1;
+    }
+    TurnDetailPanel .tool-name {
+        color: $warning;
+        text-style: bold;
+    }
+    TurnDetailPanel .tool-input {
+        color: $text-muted;
+        margin-left: 2;
+    }
+    TurnDetailPanel .tool-output {
+        color: $success;
+        margin-left: 2;
+    }
+    TurnDetailPanel #turn-footer {
+        height: 1;
+        color: $text-disabled;
+        text-align: center;
+    }
+    """
+
+    def __init__(self, turn_num: int, msg: Message) -> None:
+        super().__init__()
+        self._turn_num = turn_num
+        self._msg = msg
+
+    def compose(self) -> ComposeResult:
+        with Vertical():
+            yield Static("", id="turn-header")
+            with ScrollableContainer():
+                yield Static("", id="turn-body")
+            yield Static("ESC / q — close", id="turn-footer")
+
+    def on_mount(self) -> None:
+        msg = self._msg
+        role_color = "cyan" if msg.role == "user" else "green"
+
+        self.query_one("#turn-header", Static).update(
+            f"[bold]Turn #{self._turn_num}[/bold]  "
+            f"[{role_color}]{msg.role}[/{role_color}]  "
+            f"[dim]{(msg.token_count or 0):,} tokens[/dim]"
+            + (f"  [yellow]{len(msg.tool_calls)} call(s)[/yellow]" if msg.tool_calls else "")
+            + (f"  [magenta]{len(msg.tool_results)} result(s)[/magenta]" if msg.tool_results else "")
+        )
+
+        parts: list[str] = []
+
+        # ── Text content ────────────────────────────────────────────────────
+        if msg.content:
+            parts.append("[bold dim]── Content ──[/bold dim]")
+            parts.append(msg.content)
+
+        # ── Tool calls ──────────────────────────────────────────────────────
+        if msg.tool_calls:
+            parts.append("\n[bold dim]── Tool Calls ──[/bold dim]")
+            for i, tc in enumerate(msg.tool_calls, 1):
+                name = tc.get("name", "?")
+                raw_input = tc.get("input", "")
+                try:
+                    formatted = json.dumps(json.loads(raw_input), indent=2)
+                except (json.JSONDecodeError, TypeError):
+                    formatted = raw_input
+                parts.append(f"[bold yellow]{i}. {name}[/bold yellow]")
+                parts.append(f"[dim]{formatted}[/dim]")
+
+        # ── Tool results ────────────────────────────────────────────────────
+        if msg.tool_results:
+            parts.append("\n[bold dim]── Tool Results ──[/bold dim]")
+            for i, tr in enumerate(msg.tool_results, 1):
+                output = tr.get("output", "")
+                parts.append(f"[bold green]Result {i}[/bold green]")
+                parts.append(f"[dim]{output}[/dim]")
+
+        self.query_one("#turn-body", Static).update("\n".join(parts))
 
 
 class TokensPanel(ModalScreen):
@@ -57,24 +171,40 @@ class TokensPanel(ModalScreen):
         super().__init__()
         self._session_id = session_id
         self._db_path = db_path
+        self._messages: list[Message] = []
 
     def compose(self) -> ComposeResult:
         with Vertical():
             yield Static("", id="tokens-header")
             yield Static("", id="tokens-stats")
-            yield DataTable(id="tokens-table", show_cursor=True, zebra_stripes=True)
-            yield Static("ESC / q — close", id="tokens-footer")
+            yield DataTable(id="tokens-table", show_cursor=True, zebra_stripes=True, cursor_type="row")
+            yield Static("ESC / q — close  │  Enter — view turn", id="tokens-footer")
 
     def on_mount(self) -> None:
         self._load()
 
+    def on_data_table_row_selected(self, event: DataTable.RowSelected) -> None:
+        row_idx = event.cursor_row
+        if 0 <= row_idx < len(self._messages):
+            self.app.push_screen(TurnDetailPanel(row_idx + 1, self._messages[row_idx]))
+
     def _load(self) -> None:
-        from contextforge.core.db import get_db
+        from contextforge.adapters.registry import get_adapter
+        from contextforge.core.db import get_db, get_session
         from contextforge.core.token_analyzer import analyze_tokens
 
         db = get_db(self._db_path)
         report = analyze_tokens(db, self._session_id)
 
+        # Load messages so TurnDetailPanel can show full content
+        row = get_session(db, self._session_id)
+        if row is not None:
+            try:
+                adapter = get_adapter(row["tool"])
+                self._messages = adapter.load_messages(self._session_id)
+            except Exception:
+                self._messages = []
+
         header = self.query_one("#tokens-header", Static)
         stats = self.query_one("#tokens-stats", Static)
         table = self.query_one("#tokens-table", DataTable)
@@ -92,18 +222,28 @@ class TokensPanel(ModalScreen):
 
         # ── Stats bar ───────────────────────────────────────────────────────
         max_t = report.max_turn
+        tool_summary = ""
+        if report.has_tool_data:
+            tool_summary = (
+                f"  │  [yellow]Calls {report.tool_call_total:,}[/yellow]"
+                f"  [magenta]Results {report.tool_result_total:,}[/magenta]"
+            )
         stats.update(
             f"Total [bold]{report.total:,}[/bold] tokens  │  "
             f"[cyan]User {report.user_total:,}[/cyan] (avg {report.avg_user:,.0f})  │  "
             f"[green]Asst {report.assistant_total:,}[/green] (avg {report.avg_assistant:,.0f})  │  "
             f"{report.turn_count} turns"
+            + tool_summary
             + (f"  │  Heaviest: turn #{max_t.turn} "
                f"[bold]{max_t.tokens:,}[/bold] tok [{max_t.role}]"
                if max_t else "")
         )
 
         # ── Table ────────────────────────────────────────────────────────────
-        table.add_columns("#", "Role", "Tokens", "Cumul.", "Bar", "Preview")
+        if report.has_tool_data:
+            table.add_columns("#", "Role", "Tokens", "Text", "Calls", "Results", "Cumul.", "Bar", "Preview")
+        else:
+            table.add_columns("#", "Role", "Tokens", "Cumul.", "Bar", "Preview")
 
         max_tokens = max(t.tokens for t in report.turns)
 
@@ -120,15 +260,31 @@ class TokensPanel(ModalScreen):
                 role_str = f"[dim]{t.role}[/dim]"
                 bar_str = f"[dim]{'█' * bar_len}[/dim]"
 
-            table.add_row(
-                str(t.turn),
-                role_str,
-                f"{t.tokens:,}",
-                f"{t.cumulative:,}",
-                bar_str,
-                t.content_preview,
-            )
+            if report.has_tool_data:
+                calls_str = f"[yellow]{t.tool_call_tokens:,}[/yellow]" if t.tool_call_tokens else "[dim]—[/dim]"
+                results_str = f"[magenta]{t.tool_result_tokens:,}[/magenta]" if t.tool_result_tokens else "[dim]—[/dim]"
+                table.add_row(
+                    str(t.turn),
+                    role_str,
+                    f"{t.tokens:,}",
+                    f"{t.text_tokens:,}",
+                    calls_str,
+                    results_str,
+                    f"{t.cumulative:,}",
+                    bar_str,
+                    t.content_preview,
+                )
+            else:
+                table.add_row(
+                    str(t.turn),
+                    role_str,
+                    f"{t.tokens:,}",
+                    f"{t.cumulative:,}",
+                    bar_str,
+                    t.content_preview,
+                )
 
-        # Highlight the heaviest row
+        # Highlight the heaviest row and ensure the table has focus
         if max_t:
             table.move_cursor(row=max_t.turn - 1)
+        table.focus()

contextforge/utils/tokens.py

@@ -3,15 +3,23 @@ from __future__ import annotations
 
 import tiktoken
 
-_ENCODING = tiktoken.get_encoding("cl100k_base")
+_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(_ENCODING.encode(text))
+    return len(_get_encoding().encode(text))
 
 
 def truncate_to_budget(text: str, budget: int) -> str:
-    tokens = _ENCODING.encode(text)
+    enc = _get_encoding()
+    tokens = enc.encode(text)
     if len(tokens) <= budget:
         return text
-    return _ENCODING.decode(tokens[:budget])
+    return enc.decode(tokens[:budget])