@caffeineai/mcp 0.1.0-dev.23 → 0.1.0-dev.25

package/README.md

@@ -1,79 +1,44 @@
 # @caffeineai/mcp
 
-MCP server that gives AI coding tools access to Caffeine projects.
+An MCP server that exposes Caffeine auth, project, build, config, and chat
+operations to AI coding hosts.
 
 ## Development Release
 
-This is a DEV release. It is published under the npm `dev` dist-tag and is subject to a rapid release cadence. Expect frequent updates while the CLI and MCP packages settle.
+This is a DEV release. It is published under the npm `dev` dist-tag and is
+subject to a rapid release cadence. Expect frequent updates while the MCP
+package settles.
 
-Once installed and authenticated, your agent can list, clone, build, check, and preview Caffeine projects from inside your editor.
-
-## Prerequisites
-
-Node.js 20 or later.
-
-```bash
-node --version
-```
-
-The MCP server includes its own auth tools. You do not need to install or log in with the CLI first.
-
-## Pre-Warm The Package Cache
-
-The published package contains a native binary. `npx -y` caches it after the first download, but the first invocation often happens inside an MCP host process with a startup timeout. On a slow connection the host can mark the server as offline before the download finishes.
-
-Run this once in a terminal before relying on the server from any host:
+## Quick Start
 
 ```bash
 npx -y @caffeineai/mcp@dev --version
 ```
 
-After that, hosts on the same machine start the server from cache. Subsequent runs only re-download when a newer dev version has been published.
+The first run pre-warms the package cache. That matters because MCP hosts often
+apply startup timeouts, and a cold binary download can make the server look
+offline even though the install is still in progress.
 
-## Check The Installed Version
-
-For minimal output:
-
-```bash
-npx -y @caffeineai/mcp@dev --version
-```
-
-For the standard JSON envelope:
-
-```bash
-npx -y @caffeineai/mcp@dev --version --json
-```
+The server includes its own auth tools. You do not need to install the CLI
+first.
 
 ## Install Into Your Host
 
-All snippets below use the stdio transport with `npx -y @caffeineai/mcp@dev` as the command.
-
 ### Claude Code
 
-User-wide:
-
 ```bash
 claude mcp add --transport stdio --scope user caffeine -- npx -y @caffeineai/mcp@dev
 ```
 
-Project-wide, in `.mcp.json`:
+### OpenAI Codex
 
-```json
-{
-  "mcpServers": {
-    "caffeine": {
-      "command": "npx",
-      "args": ["-y", "@caffeineai/mcp@dev"]
-    }
-  }
-}
+```bash
+codex mcp add caffeine -- npx -y @caffeineai/mcp@dev
 ```
 
-Inside Claude Code, type `/mcp` to see server status.
-
 ### Cursor
 
-`.cursor/mcp.json` for a project, or `~/.cursor/mcp.json` globally:
+Add this to `.cursor/mcp.json` or `~/.cursor/mcp.json`:
 
 ```json
 {
@@ -87,49 +52,15 @@ Inside Claude Code, type `/mcp` to see server status.
 }
 ```
 
-Restart Cursor after adding the config.
-
 ### VS Code With GitHub Copilot
 
 ```bash
 code --add-mcp '{"name":"caffeine","command":"npx","args":["-y","@caffeineai/mcp@dev"]}'
 ```
 
-Or `.vscode/mcp.json`:
-
-```json
-{
-  "servers": {
-    "caffeine": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@caffeineai/mcp@dev"]
-    }
-  }
-}
-```
-
-Verify via the command palette: `MCP: List Servers`.
-
-### OpenAI Codex
-
-```bash
-codex mcp add caffeine -- npx -y @caffeineai/mcp@dev
-```
-
-Or `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.caffeine]
-command = "npx"
-args = ["-y", "@caffeineai/mcp@dev"]
-```
-
-Verify with `codex mcp list`.
-
 ### Windsurf
 
-`~/.codeium/windsurf/mcp_config.json`:
+Add this to `~/.codeium/windsurf/mcp_config.json`:
 
 ```json
 {
@@ -142,29 +73,55 @@ Verify with `codex mcp list`.
 }
 ```
 
-Quit and reopen Windsurf after adding the config.
-
 ## Available Tools
 
-| Tool | Description |
-| --- | --- |
-| `caffeine_auth_login` | Start a login flow. Returns an auth URL by default, or a device code when called with `deviceFlow: true` |
-| `caffeine_auth_logout` | Log out and clear local credentials |
-| `caffeine_auth_status` | Check authentication status |
-| `caffeine_list_projects` | List your projects |
-| `caffeine_show_project` | Get project details |
-| `caffeine_create_project` | Create a project |
-| `caffeine_delete_project` | Delete a project |
-| `caffeine_clone_project` | Clone a project locally |
-| `caffeine_import_project` | Import a project from a .zip |
-| `caffeine_export_project` | Export the current project to a .zip |
-| `caffeine_build` | Build the project |
-| `caffeine_check` | Validate code and configuration |
-| `caffeine_preview` | Upload a built project as a draft |
-| `caffeine_doctor` | Diagnose the local toolchain |
-| `caffeine_config_list` / `caffeine_config_get` / `caffeine_config_set` | Manage CLI config |
-
-All tools return the same stable `{ ok, data }` / `{ ok, error }` envelope used by the CLI's `--json` mode.
+| Group | Tool | Description |
+| --- | --- | --- |
+| Auth | `caffeine_auth_login` | Start a browser or device login flow |
+| Auth | `caffeine_auth_logout` | Log out and clear local credentials |
+| Auth | `caffeine_auth_status` | Check authentication status |
+| Projects | `caffeine_list_projects` | List projects |
+| Projects | `caffeine_show_project` | Get project details |
+| Projects | `caffeine_create_project` | Create a project |
+| Projects | `caffeine_delete_project` | Delete a project |
+| Projects | `caffeine_clone_project` | Clone a project locally |
+| Local | `caffeine_import_project` | Import a project from a `.zip` |
+| Local | `caffeine_export_project` | Export the current project to a `.zip` |
+| Build | `caffeine_build` | Build the project |
+| Build | `caffeine_check` | Validate code and configuration |
+| Build | `caffeine_preview` | Upload a built project as a draft |
+| Config | `caffeine_config_list` / `caffeine_config_get` / `caffeine_config_set` | Manage CLI config |
+| Env | `caffeine_doctor` | Diagnose local toolchain health |
+| Chat | `caffeine_chat_start_session` | Start a chat session |
+| Chat | `caffeine_chat_active_sessions` | Discover likely active chat sessions |
+| Chat | `caffeine_chat_resume_session` | Reattach and wait for the next stable state |
+| Chat | `caffeine_chat_watch_session` | Stream live session updates |
+| Chat | `caffeine_chat_session_status` | Summarize an active session |
+| Chat | `caffeine_chat_session_transcript` | Show the current transcript |
+| Chat | `caffeine_chat_session_feed` | Collect raw feed events |
+| Chat | `caffeine_chat_detach_session` | Mark a client-side session as detached |
+| Chat | `caffeine_chat_send` | Send a prompt |
+| Chat | `caffeine_chat_reply` | Send a freeform clarification reply |
+| Chat | `caffeine_chat_list` | List chat messages |
+| Chat | `caffeine_chat_tail` | Poll messages until the AI reaches a stable state |
+| Chat | `caffeine_chat_submit_form` | Submit a structured clarification form reply |
+| Chat | `caffeine_chat_url` | Return the browser chat URL |
+
+These tools sit on top of `@caffeine/sdk`, so they use the same underlying
+chat contract as the CLI.
+
+## Example Operations
+
+- Log in from your MCP host, then inspect or clone projects
+- Build, check, preview, import, export, or diagnose a local project from the same host
+- Start an interactive chat session and watch it live
+- Detach and later resume or inspect likely active sessions
+- Read the high-level session status, transcript, or raw feed events
+- Submit a structured clarification form from a `system_dialog` message
+- Hand off to the browser chat when needed
+
+All tools return the same stable `{ ok, data }` / `{ ok, error }` envelope
+used by the CLI's `--json` mode.
 
 ## Supported Platforms
 
@@ -176,22 +133,11 @@ Native binaries ship for:
 
 ## Troubleshooting
 
-- **Server shows as offline on first use.** Run `npx -y @caffeineai/mcp@dev --version` in a terminal, then restart your host.
-- **Not logged in errors.** Ask your MCP host to call `caffeine_auth_login`, complete the browser or device-code flow, then call `caffeine_auth_status`.
-- **Config changes not taking effect.** Most hosts do not hot-reload MCP configs. Restart the host after editing MCP config files.
-- **`command not found: npx`.** Install Node.js 20+ and ensure `npx` is on your `PATH`.
-
-## Quick Transport Check
-
-With no host running, you can pipe a JSON-RPC request directly:
-
-```bash
-echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | npx -y @caffeineai/mcp@dev
-```
-
-## Links
-
-- Caffeine platform: https://caffeine.ai
-- Model Context Protocol: https://modelcontextprotocol.io
+- If the server appears offline on first use, run `npx -y @caffeineai/mcp@dev --version` in a terminal, then restart the host.
+- If you see auth errors, call `caffeine_auth_login`, complete the flow, then call `caffeine_auth_status`.
+- `caffeine_chat_watch_session` and `caffeine_chat_resume_session` are the
+  main live-session tools for interactive hosts.
+- `caffeine_chat_feed` exposes raw project feed events when a host wants lower
+  level progress data.
 
 This package installs the matching platform binary through npm optional dependencies. Install the main package rather than a platform package directly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caffeineai/mcp",
-  "version": "0.1.0-dev.23",
+  "version": "0.1.0-dev.25",
   "description": "Caffeine MCP server",
   "homepage": "https://caffeine.ai",
   "license": "SEE LICENSE IN LICENSE",
@@ -13,14 +13,14 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@caffeineai/mcp-darwin-arm64": "0.1.0-dev.23",
-    "@caffeineai/mcp-darwin-x64": "0.1.0-dev.23",
-    "@caffeineai/mcp-linux-arm64-glibc": "0.1.0-dev.23",
-    "@caffeineai/mcp-linux-x64-glibc": "0.1.0-dev.23",
-    "@caffeineai/mcp-linux-arm64-musl": "0.1.0-dev.23",
-    "@caffeineai/mcp-linux-x64-musl": "0.1.0-dev.23",
-    "@caffeineai/mcp-win32-arm64": "0.1.0-dev.23",
-    "@caffeineai/mcp-win32-x64": "0.1.0-dev.23"
+    "@caffeineai/mcp-darwin-arm64": "0.1.0-dev.25",
+    "@caffeineai/mcp-darwin-x64": "0.1.0-dev.25",
+    "@caffeineai/mcp-linux-arm64-glibc": "0.1.0-dev.25",
+    "@caffeineai/mcp-linux-x64-glibc": "0.1.0-dev.25",
+    "@caffeineai/mcp-linux-arm64-musl": "0.1.0-dev.25",
+    "@caffeineai/mcp-linux-x64-musl": "0.1.0-dev.25",
+    "@caffeineai/mcp-win32-arm64": "0.1.0-dev.25",
+    "@caffeineai/mcp-win32-x64": "0.1.0-dev.25"
   },
   "preferGlobal": true,
   "publishConfig": {
@@ -29,6 +29,6 @@
   "caffeine": {
     "distribution": "npmjs",
     "packageName": "@caffeineai/mcp",
-    "publishedAt": "2026-05-11T22:56:21.470Z"
+    "publishedAt": "2026-05-12T19:39:42.805Z"
   }
 }