A minimal FastMCP 2.x server in TypeScript that exposes one RPC—retrieveDocs(question)—which returns raw ranked chunks from OpenAI File Search.
- Acts as a simple proxy to OpenAI's
/v1/responsesendpoint using thefile_searchtool. - Reads
OPENAI_API_KEYfrom environment variables. - Reads
vectorStoreIdfromconfig.json. - Uses FastMCP 2.x with
addToolandctx.log. - Returns raw chunks (
{ id, text, score }[]) as a JSON string, extracted fromfile_search_call.results. - Includes robustness features: 30s timeout, retry logic (3 attempts) for transient errors (429, 5xx, network), and structured error reporting.
- Optional verbose logging via
DEBUG_OPENAIenvironment variable.
- Node.js (v18 or later recommended)
- npm (or pnpm/yarn)
- An OpenAI API Key
- An existing OpenAI Vector Store ID
- Git (for cloning)
-
Clone the repository (if applicable):
# git clone <repository-url> # cd filesearch-mcp-server
-
Install dependencies: Installs required packages.
npm install
-
Configure:
-
config.json: Copyconfig.template.jsontoconfig.jsonand add your Vector Store ID.cp config.template.json config.json
Then edit
config.json:{ "vectorStoreId": "vs_YOUR_VECTOR_STORE_ID" }(Replace
vs_YOUR_VECTOR_STORE_IDwith your actual ID. This file is ignored by git via.gitignore.) -
Environment Variables: Create a
.envfile (or set environment variables directly). You can copy the example:cp .env.example .env
Then edit
.envwith your API key:# Required: Your OpenAI API Key OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # Optional: Set to "true" or "1" for verbose OpenAI API response logging # DEBUG_OPENAI=false
(This file is ignored by git via
.gitignore.)Alternatively, configure via Cline MCP Settings (
cline_mcp_setting.json):{ "servers": [ { "id": "filesearch-mcp-server", "command": "npm start", "working_directory": "path/to/filesearch-mcp-server", "environment": { "OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "DEBUG_OPENAI": "false" } } ] }
-
-
Build the TypeScript code:
npm run build
npm startThis command runs node dist/server.js, starting the server using the stdio transport (default). It listens for MCP requests on standard input/output, making it suitable for use with Cline or other MCP clients expecting stdio communication.
- Build:
npm run build(Compiles TypeScript todist/) - Format:
npm run format(Formats code with Prettier) - Lint:
npm run lint(Checks code style with ESLint) - Watch & Run:
npm run dev(Watches for changes, rebuilds, and restarts the server)
The server extracts chunks from the output[*].file_search_call.results field in the OpenAI API response. Each chunk in the returned JSON array follows the Chunk interface: { id: string, text: string, score: number }. The id is taken from the result object's id field (with a fallback), text is the chunk content, and score is the relevance score provided by OpenAI.
This project is licensed under the MIT License - see the LICENSE file for details.