diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json deleted file mode 100644 index 225a43c..0000000 --- a/.codex-plugin/plugin.json +++ /dev/null @@ -1,22 +0,0 @@ -{ - "name": "project-context-reader", - "version": "0.3.6+codex.20260927134500", - "description": "A read-only MCP plugin for selected local projects in Codex and ChatGPT Developer mode.", - "author": { - "name": "Deng Zitao" - }, - "interface": { - "displayName": "Project Context Reader", - "shortDescription": "Select and read a local project for planning.", - "longDescription": "A read-only MCP server with session-only project selection, repository overview, code search, file excerpts, and Git context.", - "developerName": "Deng Zitao", - "category": "Productivity", - "capabilities": [ - "Read" - ], - "defaultPrompt": [ - "Use Project Context Reader to select my project, inspect it, and propose an implementation plan. Do not modify files." - ] - }, - "mcpServers": "./.mcp.json" -} diff --git a/.mcp.json b/.mcp.json deleted file mode 100644 index dc6670c..0000000 --- a/.mcp.json +++ /dev/null @@ -1,18 +0,0 @@ -{ - "mcpServers": { - "project-context-reader": { - "command": "node", - "args": ["./server.mjs"], - "cwd": ".", - "enabled": true, - "default_tools_approval_mode": "approve", - "tools": { - "select_project": { - "approval_mode": "prompt" - } - }, - "startup_timeout_sec": 10, - "tool_timeout_sec": 30 - } - } -} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cbda275..878ca5d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,4 +14,4 @@ Keep changes small and preserve the server's read-only boundary. Add or update t ## Reporting bugs -Include your operating system, Node.js version, ChatGPT desktop version, exact request, and the MCP error text. Do not include proprietary code, access tokens, or secret file contents. +Include your operating system, Node.js version, browser version, exact request, and the MCP error text. Do not include proprietary code, access tokens, or secret file contents. diff --git a/README.md b/README.md index aa783f9..0ac91b1 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Codex Context Reader -A read-only [Model Context Protocol](https://modelcontextprotocol.io/) server that lets ChatGPT or Codex inspect a user-selected local project without pasting an entire repository into the conversation. +Use regular Chat on a Plus/Pro plan for read-only code analysis, leaving Codex usage for edits and tests. Codex Context Reader is a read-only [Model Context Protocol](https://modelcontextprotocol.io/) server that connects ChatGPT web to a user-selected project through a private Tunnel. It returns only a project overview, search matches, and bounded file excerpts. This reduces unrelated context and token use. Actual usage depends on the model and request. @@ -10,16 +10,16 @@ It returns only a project overview, search matches, and bounded file excerpts. T ## Install and ChatGPT web setup -### Recommended: give this prompt to a local Codex agent +### Optional: ask a local coding assistant to prepare the connection -Paste this into a **local Codex agent** on the computer that contains the project. It installs, tests, and prepares the private Tunnel. Account settings and the hidden key stay with you. +Paste this into a coding assistant on the computer that contains the project. It installs, tests, and prepares the private Tunnel. Account settings and the hidden key stay with you. ```text -Set up https://github.com/dangzitou/codex-context-reader on this computer for read-only use with Codex and, if available, regular ChatGPT web. Make the smallest necessary changes. +Set up https://github.com/dangzitou/codex-context-reader on this computer for read-only use in regular ChatGPT web through Secure MCP Tunnel. Make the smallest necessary changes. -1. Detect macOS, Linux, or Windows. Inspect the target before changing it. Clone or update the repository at ~/plugins/project-context-reader on macOS/Linux, or %USERPROFILE%\plugins\project-context-reader on Windows. Do not overwrite unrelated files. -2. Ensure Node.js 18+, Git, and ripgrep are available. Run npm test and npm run install:plugin. Verify codex plugin list shows project-context-reader@personal as installed and enabled. -3. Tell me to open chatgpt.com in a desktop browser and check Plugins → Add → Create MCP app. If unavailable, check the documented Developer mode setting under Settings → Security and login. If neither entry is available, stop the ChatGPT-Tunnel setup; the local Codex plugin can still be used. +1. Detect macOS, Linux, or Windows. Inspect the target before changing it. Clone or update the repository at ~/codex-context-reader on macOS/Linux, or %USERPROFILE%\codex-context-reader on Windows. Do not overwrite unrelated files. +2. Ensure Node.js 18+, Git, and ripgrep are available. Run npm test. +3. Tell me to open chatgpt.com in a desktop browser and check Plugins → Add → Create MCP app. If unavailable, check the documented Developer mode setting under Settings → Security and login. If neither entry is available, stop the ChatGPT-Tunnel setup. 4. Once I confirm MCP app creation is available: download tunnel-client only from the official OpenAI release or Platform Tunnel page, verify SHA-256 against the official checksum, and keep it in a user-owned local directory. Do not put it in this repository. 5. If I provide a tunnel_id, run npm run chat:tunnel -- --configure --tunnel-id . Otherwise tell me to create a Tunnel in Platform. Never create, request, print, store, or paste an API key into chat, files, Git, shell history, or logs. 6. Tell me the one remaining command to run in my own terminal: npm run chat:tunnel -- --prompt-key. Do not start the Tunnel unless I have entered the runtime key locally through that hidden prompt. @@ -37,21 +37,43 @@ Do not expose the local project to the public internet. Do not modify any select | Create a runtime API key and enter it in a local terminal | It is a credential; the launcher hides the input and does not save it. | | In ChatGPT Plugins, create the Tunnel connection | This changes your ChatGPT account settings. | -If **Create MCP app** is unavailable, check the [documented Developer mode setting](https://developers.openai.com/api/docs/guides/developer-mode) under **Settings → Security and login**. If neither entry appears, use the direct local Codex route below; restarting the Tunnel cannot add a missing ChatGPT feature. +If **Create MCP app** is unavailable, check the [documented Developer mode setting](https://developers.openai.com/api/docs/guides/developer-mode) under **Settings → Security and login**. If neither entry appears, this ChatGPT web setup is unavailable for your account; restarting the Tunnel cannot add the missing feature. + +### Install and test the server + +Requirements: Node.js 18+, Git, and [`ripgrep`](https://github.com/BurntSushi/ripgrep). Git context is optional. Install OpenAI's `tunnel-client` using the [official Tunnel guide](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels), verify its checksum, and put it on your `PATH` (or use `--client` with its absolute path in both launcher commands). + +macOS/Linux: + +```sh +git clone https://github.com/dangzitou/codex-context-reader.git "$HOME/codex-context-reader" +cd "$HOME/codex-context-reader" +npm test +``` + +Windows PowerShell: + +```powershell +git clone https://github.com/dangzitou/codex-context-reader.git "$env:USERPROFILE\codex-context-reader" +Set-Location "$env:USERPROFILE\codex-context-reader" +npm test +``` + +If the repository is already cloned, use its existing directory instead. ### Start the private Tunnel -After the agent has installed the repository, MCP app creation is available, and you have a `tunnel_id`, configure the profile once: +After the server is installed, MCP app creation is available, and you have a `tunnel_id`, configure the profile once: ```sh -cd "$HOME/plugins/project-context-reader" +cd "$HOME/codex-context-reader" npm run chat:tunnel -- --configure --tunnel-id "your-tunnel-id" ``` Windows PowerShell: ```powershell -Set-Location "$env:USERPROFILE\plugins\project-context-reader" +Set-Location "$env:USERPROFILE\codex-context-reader" npm run chat:tunnel -- --configure --tunnel-id "your-tunnel-id" ``` @@ -79,39 +101,13 @@ The key input is hidden and stays only in the launched process environment. `doc 6. Click **Try in chat**, add the app to a regular Chat if prompted, and test with a nonsensitive local repository: ```text -Use Project Context Reader to read /Users/yourname/plugins/project-context-reader. Call select_project, project_overview, search_code, and read_file, then summarize what you found with file paths. Do not modify files. +Use Project Context Reader to read /Users/yourname/codex-context-reader. Call select_project, project_overview, search_code, and read_file, then summarize what you found with file paths. Do not modify files. ``` Replace `yourname` with your username (on Windows, use the full `C:\Users\...` path). Test only if this copy of the repository contains no private data. Check the Chat tool-call details for successful `select_project`, `project_overview`, `search_code`, and `read_file` results. A green Connected badge proves the connection, not that a project was read. The project ID expires after 30 minutes; select the project again when it does. Keep `tunnel-client` running while using Chat. OpenAI documents Secure MCP Tunnel as an outbound connection for private MCP servers; it does not require an inbound public port. [Tunnel guide](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels) -## Direct local use - -For Codex Local, Codex CLI, or a local project chat, install the plugin and use `@Project Context Reader`. This is the route to use when ChatGPT web cannot create an MCP app. - -### Manual installation - -macOS/Linux: - -```sh -mkdir -p "$HOME/plugins" -git clone https://github.com/dangzitou/codex-context-reader.git "$HOME/plugins/project-context-reader" -cd "$HOME/plugins/project-context-reader" -npm run install:plugin -``` - -Windows PowerShell: - -```powershell -New-Item -ItemType Directory -Force "$env:USERPROFILE\plugins" | Out-Null -git clone https://github.com/dangzitou/codex-context-reader.git "$env:USERPROFILE\plugins\project-context-reader" -Set-Location "$env:USERPROFILE\plugins\project-context-reader" -npm run install:plugin -``` - -Requirements: Node.js 18+, Git, and [`ripgrep`](https://github.com/BurntSushi/ripgrep). Git context is optional. - ## What it reads | Tool | Purpose | diff --git a/README.zh-CN.md b/README.zh-CN.md index e1e24c9..f1345c6 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,6 +1,6 @@ # Codex Context Reader -Codex Context Reader 是一个只读 [MCP](https://modelcontextprotocol.io/) 服务，让 ChatGPT 或 Codex 在用户确认后按需读取本地项目，不必把整个仓库粘贴到对话里。 +把 Plus/Pro 的普通 Chat 用于只读项目分析，把 Codex 额度留给改代码和跑测试。Codex Context Reader 是一个只读 [MCP](https://modelcontextprotocol.io/) 服务，通过私有 Tunnel 让 ChatGPT 网页聊天按需读取用户选定的项目。 它只返回项目概览、搜索结果和有限文件片段，减少无关上下文和 token 消耗。实际消耗取决于模型和提问。 @@ -10,16 +10,16 @@ Codex Context Reader 是一个只读 [MCP](https://modelcontextprotocol.io/) 服 ## 安装与 ChatGPT 网页端配置 -### 推荐：把下面提示词交给本机 Codex Agent +### 可选：让本机编程助手准备连接 -将下面整段发送给保存项目的电脑上的 **本机 Codex Agent**。它会完成安装、测试和私有 Tunnel 准备；账户设置和隐藏输入密钥由你完成。 +将下面整段发送给保存项目的电脑上的编程助手。它会完成安装、测试和私有 Tunnel 准备；账户设置和隐藏输入密钥由你完成。 ```text -请在这台电脑上配置 https://github.com/dangzitou/codex-context-reader，用于 Codex 和在可用时用于普通 ChatGPT 网页端的只读访问。请谨慎执行，只做必要改动。 +请在这台电脑上配置 https://github.com/dangzitou/codex-context-reader，让普通 ChatGPT 网页聊天通过 Secure MCP Tunnel 只读访问项目。请谨慎执行，只做必要改动。 -1. 判断当前系统是 macOS、Linux 还是 Windows；修改前检查目标目录。macOS/Linux 使用 ~/plugins/project-context-reader，Windows 使用 %USERPROFILE%\plugins\project-context-reader。不要覆盖无关文件。 -2. 确保 Node.js 18+、Git 和 ripgrep 可用。运行 npm test 与 npm run install:plugin，并确认 codex plugin list 显示 project-context-reader@personal 已安装且已启用。 -3. 提示我用桌面浏览器打开 chatgpt.com，检查 插件 → 添加 → 创建 MCP 应用。若没有，再检查文档所述的 设置 → 账户安全与登录 → Developer mode。两个入口都没有时停止 ChatGPT-Tunnel 配置；本地 Codex 插件仍可使用。 +1. 判断当前系统是 macOS、Linux 还是 Windows；修改前检查目标目录。macOS/Linux 使用 ~/codex-context-reader，Windows 使用 %USERPROFILE%\codex-context-reader。不要覆盖无关文件。 +2. 确保 Node.js 18+、Git 和 ripgrep 可用。运行 npm test。 +3. 提示我用桌面浏览器打开 chatgpt.com，检查 插件 → 添加 → 创建 MCP 应用。若没有，再检查文档所述的 设置 → 账户安全与登录 → Developer mode。两个入口都没有时停止 ChatGPT-Tunnel 配置。 4. 我确认可以创建 MCP 应用后：从 OpenAI 官方发布页或 Platform Tunnel 页面下载 tunnel-client，用官方 SHA-256 清单校验，并放在用户拥有的本地目录；不要放进本仓库。 5. 如果我提供 tunnel_id，运行 npm run chat:tunnel -- --configure --tunnel-id ；如果没有，告诉我先在 Platform 创建 Tunnel。绝不创建、索取、打印、保存或把 API key 粘贴到聊天、文件、Git、Shell 历史或日志中。 6. 告诉我唯一需要在我自己终端运行的命令：npm run chat:tunnel -- --prompt-key。除非我已在本机通过隐藏输入方式输入 runtime key，否则不要启动 Tunnel。 @@ -37,21 +37,43 @@ Codex Context Reader 是一个只读 [MCP](https://modelcontextprotocol.io/) 服 | 创建 runtime API key，并在本机终端输入 | 它是凭据；启动器隐藏输入且不会保存。 | | 在 ChatGPT Plugins 中创建 Tunnel 连接 | 这会修改你的 ChatGPT 账户设置。 | -若没有 **创建 MCP 应用**，再检查 [OpenAI 文档中的 Developer mode 设置](https://developers.openai.com/api/docs/guides/developer-mode)：**设置 → 账户安全与登录**。两个入口都没有时，先用下面的本地 Codex 方式；重启 Tunnel 无法让缺失的 ChatGPT 功能出现。 +若没有 **创建 MCP 应用**，再检查 [OpenAI 文档中的 Developer mode 设置](https://developers.openai.com/api/docs/guides/developer-mode)：**设置 → 账户安全与登录**。两个入口都没有时，当前账号无法使用这套 ChatGPT 网页端连接方式；重启 Tunnel 无法让缺失的功能出现。 + +### 安装并测试服务 + +依赖：Node.js 18+、Git 和 [`ripgrep`](https://github.com/BurntSushi/ripgrep)；Git 上下文为可选能力。还需按 [OpenAI Tunnel 官方文档](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels)安装 `tunnel-client`，校验官方 SHA-256，并将其加入 `PATH`（或在两条启动命令中都用 `--client` 指定可执行文件的绝对路径）。 + +macOS/Linux： + +```sh +git clone https://github.com/dangzitou/codex-context-reader.git "$HOME/codex-context-reader" +cd "$HOME/codex-context-reader" +npm test +``` + +Windows PowerShell： + +```powershell +git clone https://github.com/dangzitou/codex-context-reader.git "$env:USERPROFILE\codex-context-reader" +Set-Location "$env:USERPROFILE\codex-context-reader" +npm test +``` + +如果仓库已经克隆，直接进入现有目录即可。 ### 启动私有 Tunnel -Agent 完成安装、确认可创建 MCP 应用且你获得 `tunnel_id` 后，首次配置 profile： +安装服务、确认可创建 MCP 应用且获得 `tunnel_id` 后，首次配置 profile： ```sh -cd "$HOME/plugins/project-context-reader" +cd "$HOME/codex-context-reader" npm run chat:tunnel -- --configure --tunnel-id "你的-tunnel-id" ``` Windows PowerShell： ```powershell -Set-Location "$env:USERPROFILE\plugins\project-context-reader" +Set-Location "$env:USERPROFILE\codex-context-reader" npm run chat:tunnel -- --configure --tunnel-id "你的-tunnel-id" ``` @@ -79,39 +101,13 @@ npm run chat:tunnel -- --prompt-key 6. 点击 **在聊天中试用**；若有提示，在普通 Chat 中加入该应用。先用无敏感信息的本地项目测试： ```text -使用 Project Context Reader 读取 /Users/你的用户名/plugins/project-context-reader。依次调用 select_project、project_overview、search_code 和 read_file，结合文件路径总结所见；不要修改文件。 +使用 Project Context Reader 读取 /Users/你的用户名/codex-context-reader。依次调用 select_project、project_overview、search_code 和 read_file，结合文件路径总结所见；不要修改文件。 ``` 把示例中的用户名换成自己的；Windows 使用完整的 `C:\Users\...` 路径。先确认这份仓库副本不含私有数据。在 Chat 的工具调用详情中确认 `select_project`、`project_overview`、`search_code` 和 `read_file` 都成功返回结果。绿色“已连接”只证明连接建立，不证明已经读取项目。项目 ID 30 分钟后失效，届时重新选择项目；使用期间保持 `tunnel-client` 运行。 OpenAI 的 Secure MCP Tunnel 是私有 MCP 的出站连接，不需要开放入站公网端口。[Tunnel 官方文档](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels) -## 本地直接使用 - -Codex Local、Codex CLI 或本地项目聊天可直接安装插件并使用 `@Project Context Reader`。ChatGPT 网页端不能创建 MCP 应用时，使用这条路径。 - -### 手动安装 - -macOS/Linux： - -```sh -mkdir -p "$HOME/plugins" -git clone https://github.com/dangzitou/codex-context-reader.git "$HOME/plugins/project-context-reader" -cd "$HOME/plugins/project-context-reader" -npm run install:plugin -``` - -Windows PowerShell： - -```powershell -New-Item -ItemType Directory -Force "$env:USERPROFILE\plugins" | Out-Null -git clone https://github.com/dangzitou/codex-context-reader.git "$env:USERPROFILE\plugins\project-context-reader" -Set-Location "$env:USERPROFILE\plugins\project-context-reader" -npm run install:plugin -``` - -依赖：Node.js 18+、Git 和 [`ripgrep`](https://github.com/BurntSushi/ripgrep)；Git 上下文为可选能力。 - ## 读取范围 | 工具 | 用途 | diff --git a/package.json b/package.json index c853395..3cd95c2 100644 --- a/package.json +++ b/package.json @@ -1,10 +1,9 @@ { "name": "codex-context-reader", "version": "0.3.6", - "description": "A read-only MCP plugin for selected local projects in Codex and ChatGPT Developer mode.", + "description": "A read-only MCP server for selected projects in regular ChatGPT web through Secure MCP Tunnel.", "type": "module", "scripts": { - "install:plugin": "node scripts/install-plugin.mjs", "test": "node test-server.mjs && node test-tunnel-script.mjs", "chat:tunnel": "node scripts/chat-tunnel.mjs" }, @@ -12,7 +11,6 @@ "chatgpt", "mcp", "model-context-protocol", - "codex", "local-repository", "token-optimization" ], diff --git a/scripts/install-plugin.mjs b/scripts/install-plugin.mjs deleted file mode 100644 index 8b1c943..0000000 --- a/scripts/install-plugin.mjs +++ /dev/null @@ -1,37 +0,0 @@ -#!/usr/bin/env node -import { mkdir, readFile, writeFile } from "node:fs/promises"; -import { homedir } from "node:os"; -import { dirname, join, resolve } from "node:path"; -import { fileURLToPath } from "node:url"; -import { spawnSync } from "node:child_process"; - -const pluginRoot = resolve(dirname(fileURLToPath(import.meta.url)), ".."); -const expectedRoot = join(homedir(), "plugins", "project-context-reader"); -if (pluginRoot !== expectedRoot) { - throw new Error(`Clone this repository to ${expectedRoot} before running the installer.`); -} - -const marketplacePath = join(homedir(), ".agents", "plugins", "marketplace.json"); -let marketplace = { name: "personal", interface: { displayName: "Personal" }, plugins: [] }; -try { - marketplace = JSON.parse(await readFile(marketplacePath, "utf8")); -} catch (cause) { - if (cause.code !== "ENOENT") throw cause; -} -if (!Array.isArray(marketplace.plugins) || typeof marketplace.name !== "string") throw new Error(`Invalid marketplace file: ${marketplacePath}`); -const entry = { - name: "project-context-reader", - source: { source: "local", path: "./plugins/project-context-reader" }, - policy: { installation: "AVAILABLE", authentication: "ON_INSTALL" }, - category: "Productivity", -}; -const index = marketplace.plugins.findIndex((plugin) => plugin.name === entry.name); -if (index === -1) marketplace.plugins.push(entry); -else marketplace.plugins[index] = entry; -await mkdir(dirname(marketplacePath), { recursive: true }); -await writeFile(marketplacePath, `${JSON.stringify(marketplace, null, 2)}\n`); - -if (process.argv.includes("--skip-codex")) process.exit(0); -const install = spawnSync("codex", ["plugin", "add", "project-context-reader@personal"], { stdio: "inherit" }); -if (install.error?.code === "ENOENT") console.log("Marketplace entry created. Install Project Context Reader from the Personal marketplace in the ChatGPT desktop app."); -else if (install.status !== 0) process.exit(install.status || 1);