# CPA Search MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org)
[![MCP](https://img.shields.io/badge/Protocol-Model%20Context%20Protocol-purple.svg)](https://modelcontextprotocol.io)

English | [中文说明](./README_CN.md)

A lightweight, **zero-dependency** Model Context Protocol (MCP) server for real-time web search and webpage content extraction.

It seamlessly reuses your existing local **CLIProxyAPI (CPA)** instance (`http://127.0.0.1:8317`) and authorized **Google Gemini, xAI Grok, Zhipu GLM** accounts to perform structured web research for AI coding agents (**Claude Code, Cursor, Codex, Windsurf, Trae**).

---

## 🌟 Key Features

- ⚡ **Zero Setup & Zero Extra Cost**: Directly uses your existing local CPA and Google/Grok/GLM credentials.
- 🎯 **Multi-Engine Support**:
  - `gemini`: Structured research summaries via Google Gemini (fast, strong global tech coverage — model knowledge, not a live crawl).
  - `glm`: Chinese & local tech research via Zhipu GLM-5.3 (fresher knowledge, deep-reasoning model; slower).
  - `grok`: xAI Grok knowledge with a real-time bias.
  - `duckduckgo`: **True live-web engine** — scrapes DuckDuckGo HTML and automatically falls back to Bing when bot-challenged. No API keys.
  - `auto`: gemini → glm → live-web automatic failover.
- 🛡️ **Proxy-aware networking**: live-web fetches (DuckDuckGo/Bing/`fetch_webpage`) tunnel through your HTTP proxy via zero-dependency CONNECT, trying `CPA_SEARCH_PROXY` → `HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY` → `http://127.0.0.1:7897` → direct.
- 🌐 **Webpage Content Extraction**: Includes a built-in `fetch_webpage` tool to fetch and strip raw HTML into clean readable text.
- 🔌 **Universal Compatibility**: Works with **Claude Code**, **Cursor**, **Codex**, **Windsurf**, **Trae**, and any standard MCP client.
- 🚀 **Zero Dependencies**: Pure Node.js ESM standard library implementation. Instant startup and minimal memory footprint.

---

## 📦 Quick Start

### 1. Register with Claude Code

Run the following command in your terminal:

```bash
claude mcp add --scope user cpa-search node "C:/Users/aa182/Documents/Codex/2026-08-22/new-chat-2/repositories/cpa-search-mcp/index.mjs"
```

Verify status:
```bash
claude mcp list
```

### 2. Configure for Cursor / Windsurf / Trae / Codex

Add the following to your MCP configuration file (e.g. `claude_desktop_config.json` or Cursor MCP settings):

```json
{
  "mcpServers": {
    "cpa-search": {
      "command": "node",
      "args": [
        "C:/Users/aa182/Documents/Codex/2026-08-22/new-chat-2/repositories/cpa-search-mcp/index.mjs"
      ]
    }
  }
}
```

---

## 🛠️ Provided Tools

### 1. `cpa_search`
Search the web for up-to-date facts, documentation, and technical news.
- **Parameters**:
  - `query` (*string, required*): The search query or research topic.
  - `engine` (*string, optional*): `gemini` | `glm` | `grok` | `duckduckgo` | `auto`.

### 2. `fetch_webpage`
Fetch and extract clean text from any URL.
- **Parameters**:
  - `url` (*string, required*): The webpage URL (http/https).

---

## ⚙️ Environment Variables (Optional)

| Variable | Default | Description |
| :--- | :--- | :--- |
| `CPA_BASE_URL` | `http://127.0.0.1:8317` | Local CPA proxy address |
| `CPA_API_KEY` | *(Built-in Local Key)* | CPA authentication key |
| `CPA_SEARCH_MODEL` | `gemini-3.7-flash-high` | Model used by the `gemini` engine |
| `CPA_GLM_MODEL` | `glm-5.3-cpa` | Model used by the `glm` engine |
| `CPA_SEARCH_PROXY` | *(see chain below)* | Explicit outbound proxy for live-web fetches; set to an empty string to force direct connection |
| `HTTPS_PROXY` | falls back to `http://127.0.0.1:7897` | Outbound proxy for live-web fetches (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY` are honored) |

> Proxy resolution order for live-web fetches: `CPA_SEARCH_PROXY` → `HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY` → local Clash/mihomo default (`http://127.0.0.1:7897`) → direct connection. Local addresses (CPA itself) always go direct.

---

## 🧪 Testing

Run the automated end-to-end test suite:

```bash
node test.mjs
```

---

## 📄 License

[MIT License](./LICENSE) © 2026 ffffhx