Move settings under agentsetting; add Gemini

caidish · caidish · commit 8fa83ccc3ee1 · 2026-02-09T09:34:50.000+08:00
Move claudedesktopsetting/ and codexsetting/ into a new agentsetting/ subtree, updating all references across docs, examples, and setup scripts. Add Gemini CLI support (agentsetting/geminisetting) with README and settings.json templates. Update setup_claude.sh, claude_desktop_config.json, codex.mcp.toml, and various docs to point to the new paths, and modify instrmcp.utils.stdio_proxy to search the agentsetting path for the claude launcher. This reorganizes configuration files and adds Gemini integration while keeping launcher scripts and proxy logic intact.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -80,10 +80,13 @@ playwright install chromium
 ### Communication Flow
 ```
 Claude Desktop/Code ←→ STDIO ←→ claude_launcher.py ←→ stdio_proxy.py ←→ HTTP ←→ Jupyter MCP Server
-                              (claudedesktopsetting/)     (utils/)              (servers/jupyter_qcodes/)
+                              (agentsetting/claudedesktopsetting/)  (utils/)        (servers/jupyter_qcodes/)
 
 Codex CLI          ←→ STDIO ←→ codex_launcher.py ←→ stdio_proxy.py ←→ HTTP ←→ Jupyter MCP Server
-                              (codexsetting/)
+                              (agentsetting/codexsetting/)
+
+Gemini CLI         ←→ STDIO ←→ claude_launcher.py ←→ stdio_proxy.py ←→ HTTP ←→ Jupyter MCP Server
+                              (agentsetting/geminisetting/)
 ```
 
 ### Key Directories
diff --git a/README.md b/README.md
@@ -141,22 +141,22 @@ InstrMCP provides seamless integration with Claude Desktop for AI-assisted labor
 1. **Run Automated Setup**:
 ```bash
 cd /path/to/your/instrMCP
-./claudedesktopsetting/setup_claude.sh
+./agentsetting/claudedesktopsetting/setup_claude.sh
 ```
 
 2. **Restart Claude Desktop** completely and test with: *"What MCP tools are available?"*
 
 **Manual Setup Alternative:**
 ```bash
 # 1. Copy and edit configuration
-cp claudedesktopsetting/claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json
+cp agentsetting/claudedesktopsetting/claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json
 
 # 2. Edit the copied file - replace placeholders with actual paths:
 #    /path/to/your/python3 → $(which python3)
 #    /path/to/your/instrMCP → $(pwd)
 ```
 
-See [`claudedesktopsetting/README.md`](claudedesktopsetting/README.md) for detailed setup instructions and troubleshooting.
+See [`agentsetting/claudedesktopsetting/README.md`](agentsetting/claudedesktopsetting/README.md) for detailed setup instructions and troubleshooting.
 
 ## Claude Code Integration
 
@@ -167,7 +167,7 @@ Claude Code supports local MCP servers via STDIO. Use the provided launcher to c
 claude mcp add instrMCP --env instrMCP_PATH=$instrMCP_PATH \
   --env PYTHONPATH=$instrMCP_PATH \
   -- $instrMCP_PATH/venv/bin/python \
-  $instrMCP_PATH/claudedesktopsetting/claude_launcher.py
+  $instrMCP_PATH/agentsetting/claudedesktopsetting/claude_launcher.py
 
 # Verify connection
 /mcp
@@ -184,11 +184,34 @@ Codex expects MCP servers over STDIO. Use the Codex launcher to proxy STDIO call
 
 **Configuration:**
 - command: `python`
-- args: `["/path/to/your/instrMCP/codexsetting/codex_launcher.py"]`
+- args: `["/path/to/your/instrMCP/agentsetting/codexsetting/codex_launcher.py"]`
 - env:
   - `JUPYTER_MCP_HOST=127.0.0.1`
   - `JUPYTER_MCP_PORT=8123`
 
+## Gemini CLI Integration
+
+Gemini CLI supports MCP servers over STDIO. Use the same launcher as Claude Desktop:
+
+**Configuration** (`~/.gemini/settings.json`):
+```json
+{
+  "mcpServers": {
+    "instrMCP": {
+      "command": "/path/to/your/python",
+      "args": ["/path/to/your/instrMCP/agentsetting/claudedesktopsetting/claude_launcher.py"],
+      "env": {
+        "instrMCP_PATH": "/path/to/your/instrMCP",
+        "PYTHONPATH": "/path/to/your/instrMCP"
+      },
+      "trust": true
+    }
+  }
+}
+```
+
+See [`agentsetting/geminisetting/README.md`](agentsetting/geminisetting/README.md) for detailed setup instructions.
+
 ## V2.0.0 Features (Current Release)
 
 ### 1. Resource Discovery Tool
diff --git a/agentsetting/claudedesktopsetting/CLAUDE_DESKTOP_SETUP.md b/agentsetting/claudedesktopsetting/CLAUDE_DESKTOP_SETUP.md
@@ -52,7 +52,7 @@ Add this configuration to your `claude_desktop_config.json`:
     "jupyter-qcodes": {
       "command": "${instrMCP_PATH}/venv/bin/python",
       "args": [
-        "${instrMCP_PATH}/claudedesktopsetting/claude_launcher.py"
+        "${instrMCP_PATH}/agentsetting/claudedesktopsetting/claude_launcher.py"
       ],
       "cwd": "${instrMCP_PATH}",
       "env": {
diff --git a/agentsetting/claudedesktopsetting/README.md b/agentsetting/claudedesktopsetting/README.md
@@ -14,7 +14,7 @@ This directory contains Claude Desktop launcher and configuration files for Inst
 **Automated (Recommended):**
 ```bash
 cd /path/to/instrMCP
-./claudedesktopsetting/setup_claude.sh
+./agentsetting/claudedesktopsetting/setup_claude.sh
 ```
 
 **Manual Setup:**
diff --git a/agentsetting/claudedesktopsetting/claude_desktop_config.json b/agentsetting/claudedesktopsetting/claude_desktop_config.json
@@ -3,7 +3,7 @@
     "instrmcp-jupyter": {
       "command": "/path/to/your/python3",
       "args": [
-        "/path/to/your/instrMCP/claudedesktopsetting/claude_launcher.py"
+        "/path/to/your/instrMCP/agentsetting/claudedesktopsetting/claude_launcher.py"
       ],
       "env": {
         "PYTHONPATH": "/path/to/your/instrMCP",
diff --git a/agentsetting/claudedesktopsetting/claude_launcher.py b/agentsetting/claudedesktopsetting/claude_launcher.py
diff --git a/agentsetting/claudedesktopsetting/setup_claude.sh b/agentsetting/claudedesktopsetting/setup_claude.sh
@@ -22,9 +22,9 @@ echo "   InstrMCP: $INSTRMCP_PATH"
 echo "   Python:   $PYTHON_PATH"
 
 # Check if we're in the right directory
-if [ ! -f "$INSTRMCP_PATH/claudedesktopsetting/claude_launcher.py" ]; then
+if [ ! -f "$INSTRMCP_PATH/agentsetting/claudedesktopsetting/claude_launcher.py" ]; then
     echo "❌ Error: Please run this script from the instrMCP root directory"
-    echo "   Expected to find: claudedesktopsetting/claude_launcher.py"
+    echo "   Expected to find: agentsetting/claudedesktopsetting/claude_launcher.py"
     exit 1
 fi
 
@@ -61,7 +61,7 @@ cat > "$CONFIG_PATH" <<EOF
     "instrmcp-jupyter": {
       "command": "$PYTHON_PATH",
       "args": [
-        "$INSTRMCP_PATH/claudedesktopsetting/claude_launcher.py"
+        "$INSTRMCP_PATH/agentsetting/claudedesktopsetting/claude_launcher.py"
       ],
       "env": {
         "PYTHONPATH": "$INSTRMCP_PATH",
diff --git a/agentsetting/codexsetting/README.md b/agentsetting/codexsetting/README.md
@@ -8,23 +8,23 @@ Usage
 - Install this project into the Python env Codex will use: `pip install -e .` from the repo root.
 - Configure Codex to launch an MCP server over STDIO using this command:
   - command: `python`
-  - args: `["/path/to/instrMCP/codexsetting/codex_launcher.py"]`
+  - args: `["/path/to/instrMCP/agentsetting/codexsetting/codex_launcher.py"]`
   - env (recommended):
     - `JUPYTER_MCP_HOST=127.0.0.1`
     - `JUPYTER_MCP_PORT=8123`
 
 Using the TOML config
-- A ready-to-use MCP config is provided at `codexsetting/codex.mcp.toml`.
+- A ready-to-use MCP config is provided at `agentsetting/codexsetting/codex.mcp.toml`.
 - Options to use it (adapt to your Codex version):
   - Merge: copy the `[mcp.servers.instr_mcp]` section into your main Codex config file.
-  - Direct: if supported, point Codex to this file, e.g. `codex --mcp-config /path/to/instrMCP/codexsetting/codex.mcp.toml`.
+  - Direct: if supported, point Codex to this file, e.g. `codex --mcp-config /path/to/instrMCP/agentsetting/codexsetting/codex.mcp.toml`.
 - Paths: If your Codex does not expand `${...}`, replace with absolute paths in the TOML as noted in comments.
 - Env: Ensure the Python used by Codex has this repo installed (`pip install -e .`).
 
 Example (conceptual) config entry
 - id: `instr_mcp`
 - command: `python`
-- args: `["${instrMCP_PATH}/codexsetting/codex_launcher.py"]`
+- args: `["${instrMCP_PATH}/agentsetting/codexsetting/codex_launcher.py"]`
 - env:
   - `PYTHONPATH=${instrMCP_PATH}`
   - `instrMCP_PATH=${instrMCP_PATH}`
diff --git a/agentsetting/codexsetting/codex.mcp.toml b/agentsetting/codexsetting/codex.mcp.toml
@@ -5,7 +5,7 @@
 
 [mcp_servers.instr_mcp]
 command = "python"
-args = ["${instrMCP_PATH}/codexsetting/codex_launcher.py"]
+args = ["${instrMCP_PATH}/agentsetting/codexsetting/codex_launcher.py"]
 
 # Optional: set a working directory
 cwd = "${instrMCP_PATH}"
@@ -14,7 +14,7 @@ cwd = "${instrMCP_PATH}"
 env = { JUPYTER_MCP_HOST = "127.0.0.1",JUPYTER_MCP_PORT = "8123",PYTHONPATH = "${instrMCP_PATH}",instrMCP_PATH = "${instrMCP_PATH}"}
 
 # If your Codex build does not expand ${...}, replace with absolute paths, e.g.:
-# args = ["/Users/you/instrMCP/codexsetting/codex_launcher.py"]
+# args = ["/Users/you/instrMCP/agentsetting/codexsetting/codex_launcher.py"]
 # cwd = "/Users/you/instrMCP"
 # env = { PYTHONPATH = "/Users/you/instrMCP", instrMCP_PATH = "/Users/you/instrMCP", JUPYTER_MCP_HOST = "127.0.0.1", JUPYTER_MCP_PORT = "8123" }
 
diff --git a/agentsetting/codexsetting/codex_launcher.py b/agentsetting/codexsetting/codex_launcher.py
diff --git a/agentsetting/geminisetting/README.md b/agentsetting/geminisetting/README.md
@@ -0,0 +1,75 @@
+# Gemini CLI Setup for InstrMCP
+
+This folder contains the Gemini CLI configuration template for InstrMCP.
+
+Gemini CLI uses the same STDIO launcher as Claude Desktop, proxying MCP requests to the Jupyter HTTP server.
+
+## Quick Setup
+
+1. Copy the template to your Gemini config directory:
+
+```bash
+mkdir -p ~/.gemini
+cp agentsetting/geminisetting/settings.json ~/.gemini/settings.json
+```
+
+2. Edit `~/.gemini/settings.json` — replace placeholders with actual paths:
+   - `/path/to/your/python` → your Python path (e.g., `which python`)
+   - `/path/to/your/instrMCP` → your instrMCP directory (e.g., `~/GitHub/instrMCP`)
+
+3. Start your Jupyter MCP server:
+
+```bash
+jupyter lab
+# In a notebook cell:
+# %load_ext instrmcp.extensions
+# %mcp_start
+```
+
+4. Run Gemini CLI — it will connect via STDIO to the launcher.
+
+## Configuration
+
+```json
+{
+  "mcpServers": {
+    "instrMCP": {
+      "command": "/path/to/your/python",
+      "args": ["/path/to/your/instrMCP/agentsetting/claudedesktopsetting/claude_launcher.py"],
+      "env": {
+        "instrMCP_PATH": "/path/to/your/instrMCP",
+        "PYTHONPATH": "/path/to/your/instrMCP"
+      },
+      "trust": true
+    }
+  }
+}
+```
+
+**Fields:**
+- `command`: Full path to Python executable
+- `args`: Path to the STDIO launcher script
+- `env`: Environment variables for the launcher
+- `trust`: Allow the MCP server to run without prompting
+
+## How It Works
+
+```
+Gemini CLI ←→ STDIO ←→ claude_launcher.py ←→ stdio_proxy ←→ HTTP ←→ Jupyter MCP Server
+```
+
+The launcher reuses the shared STDIO-HTTP proxy in `instrmcp.utils.stdio_proxy`.
+
+## Troubleshooting
+
+**Gemini shows no tools:**
+- Ensure Jupyter is running with the MCP extension loaded and started
+- Check that `~/.gemini/settings.json` has correct absolute paths
+
+**"spawn python ENOENT":**
+- Use full path to Python executable in the `command` field
+- Test: `/full/path/to/python --version`
+
+**Launcher import errors:**
+- Ensure instrMCP is installed: `pip install -e .`
+- Check PYTHONPATH in the env section
diff --git a/agentsetting/geminisetting/settings.json b/agentsetting/geminisetting/settings.json
@@ -0,0 +1,15 @@
+{
+  "mcpServers": {
+    "instrMCP": {
+      "command": "/path/to/your/python",
+      "args": [
+        "/path/to/your/instrMCP/agentsetting/claudedesktopsetting/claude_launcher.py"
+      ],
+      "env": {
+        "instrMCP_PATH": "/path/to/your/instrMCP",
+        "PYTHONPATH": "/path/to/your/instrMCP"
+      },
+      "trust": true
+    }
+  }
+}
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -49,7 +49,7 @@ Claude Desktop/Code ←→ STDIO ←→ claude_launcher.py ←→ stdio_proxy.py
 
 The system uses a proxy pattern:
 1. External clients (Claude Desktop, Claude Code, Codex) communicate via STDIO
-2. Launchers (`claudedesktopsetting/claude_launcher.py`, `codexsetting/codex_launcher.py`) bridge STDIO to HTTP
+2. Launchers (`agentsetting/claudedesktopsetting/claude_launcher.py`, `agentsetting/codexsetting/codex_launcher.py`) bridge STDIO to HTTP
 3. The actual MCP server runs as an HTTP server within Jupyter
 
 ### QCodes Integration
@@ -392,7 +392,7 @@ python tests/playwright/test_metadata_consistency.py --mode snapshot
   "mcpServers": {
     "instrmcp-jupyter": {
       "command": "/path/to/your/python3",
-      "args": ["/path/to/your/instrMCP/claudedesktopsetting/claude_launcher.py"],
+      "args": ["/path/to/your/instrMCP/agentsetting/claudedesktopsetting/claude_launcher.py"],
       "env": {
         "PYTHONPATH": "/path/to/your/instrMCP",
         "instrMCP_PATH": "/path/to/your/instrMCP",
@@ -410,17 +410,37 @@ python tests/playwright/test_metadata_consistency.py --mode snapshot
 claude mcp add instrMCP --env instrMCP_PATH=$instrMCP_PATH \
   --env PYTHONPATH=$instrMCP_PATH \
   -- $instrMCP_PATH/venv/bin/python \
-  $instrMCP_PATH/claudedesktopsetting/claude_launcher.py
+  $instrMCP_PATH/agentsetting/claudedesktopsetting/claude_launcher.py
 ```
 
 ### Codex CLI Integration
 
 - Command: `python`
-- Args: `["/path/to/your/instrMCP/codexsetting/codex_launcher.py"]`
+- Args: `["/path/to/your/instrMCP/agentsetting/codexsetting/codex_launcher.py"]`
 - Env:
   - `JUPYTER_MCP_HOST=127.0.0.1`
   - `JUPYTER_MCP_PORT=8123`
 
+### Gemini CLI Integration
+
+Gemini uses the same STDIO launcher as Claude Desktop (`~/.gemini/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "instrMCP": {
+      "command": "/path/to/your/python",
+      "args": ["/path/to/your/instrMCP/agentsetting/claudedesktopsetting/claude_launcher.py"],
+      "env": {
+        "instrMCP_PATH": "/path/to/your/instrMCP",
+        "PYTHONPATH": "/path/to/your/instrMCP"
+      },
+      "trust": true
+    }
+  }
+}
+```
+
 ## Communication Flows
 
 ### STDIO-based Clients (Claude Desktop, Claude Code, Codex)
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
@@ -243,20 +243,20 @@ python3 -c "import sys; sys.path.append('/full/path/to/instrMCP'); import instrm
 ```bash
 # Re-run automated setup
 cd /path/to/instrMCP
-./claudedesktopsetting/setup_claude.sh
+./agentsetting/claudedesktopsetting/setup_claude.sh
 
 # Verify generated config
 cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
 
 # Check paths are correct
 # - command: Should match $(which python3)
-# - args: Should match $(pwd)/claudedesktopsetting/claude_launcher.py
+# - args: Should match $(pwd)/agentsetting/claudedesktopsetting/claude_launcher.py
 # - env: Should match $(pwd)
 
 # Restart Claude Desktop
 ```
 
-See [`claudedesktopsetting/README.md`](../claudedesktopsetting/README.md) for detailed Claude Desktop setup instructions.
+See [`agentsetting/claudedesktopsetting/README.md`](../agentsetting/claudedesktopsetting/README.md) for detailed Claude Desktop setup instructions.
 
 ## Claude Code Integration Issues
 
@@ -275,7 +275,7 @@ claude mcp list
 claude mcp add instrMCP --env instrMCP_PATH=$instrMCP_PATH \
   --env PYTHONPATH=$instrMCP_PATH \
   -- $instrMCP_PATH/venv/bin/python \
-  $instrMCP_PATH/claudedesktopsetting/claude_launcher.py
+  $instrMCP_PATH/agentsetting/claudedesktopsetting/claude_launcher.py
 
 # Restart MCP server
 claude mcp restart instrMCP
@@ -323,7 +323,7 @@ jupyter lab
 # - JUPYTER_MCP_PORT=8123
 
 # Test launcher manually
-python /path/to/instrMCP/codexsetting/codex_launcher.py
+python /path/to/instrMCP/agentsetting/codexsetting/codex_launcher.py
 ```
 
 ## Clean Installation (Fresh Start)
diff --git a/docs/source/api/cli.rst b/docs/source/api/cli.rst
@@ -164,7 +164,7 @@ Then in notebook:
 
 .. code-block:: bash
 
-   python claudedesktopsetting/claude_launcher.py
+   python agentsetting/claudedesktopsetting/claude_launcher.py
 
 Development Workflow
 ~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst
@@ -112,7 +112,7 @@ After starting the MCP server in JupyterLab, connect Claude Desktop or Claude Co
 
 1. The server runs on ``http://127.0.0.1:8123``
 2. Configure your MCP client to connect to this endpoint
-3. Use the launcher scripts in ``claudedesktopsetting/`` or ``codexsetting/``
+3. Use the launcher scripts in ``agentsetting/claudedesktopsetting/`` or ``agentsetting/codexsetting/``
 
 Example configuration for Claude Desktop (``claude_desktop_config.json``):
 
@@ -122,7 +122,7 @@ Example configuration for Claude Desktop (``claude_desktop_config.json``):
      "mcpServers": {
        "instrMCP": {
          "command": "python",
-         "args": ["/path/to/instrMCP/claudedesktopsetting/claude_launcher.py"]
+         "args": ["/path/to/instrMCP/agentsetting/claudedesktopsetting/claude_launcher.py"]
        }
      }
    }
diff --git a/instrmcp/utils/stdio_proxy.py b/instrmcp/utils/stdio_proxy.py
