Content
# Tool List
Self-hosted remote MCP service that provides "network search + webpage retrieval" capabilities to AI programming tools (such as Claude Code / Cursor) via HTTP, along with a web-based management backend.
## Implemented Features
### MCP Service (for AI tool invocation)
- ✅ 3 MCP tools: `web_search` / `web_fetch` / `web_search_and_fetch`
- ✅ Streamable HTTP transmission (single `/mcp` endpoint)
- ✅ API Key authentication (Bearer Token)
- ✅ SSRF protection (IP range interception + DNS rebinding protection + redirect hop-by-hop verification)
- ✅ HTML → Markdown conversion (content extraction + noise removal)
- ✅ SearXNG meta-search engine integration
### Management Backend (web-based)
- ✅ Administrator password login (argon2 hash + session cookie)
- ✅ Key management: create / list / enable/disable / delete
- ✅ Request overview: total requests, distribution by tool, 14-day trend
- ✅ Single Key usage statistics: distribution by tool + trend chart
- ✅ Automatic usage recording: write to database for each MCP tool invocation
### Infrastructure
- ✅ MySQL 8.0 + Prisma ORM (data persistence)
- ✅ Usage statistics (automatic recording of keyId / toolName / time for each invocation)
- ✅ Vue 3 + Naive UI management interface (SPA)
## Quick Start
### 1. Install Dependencies
```bash
pnpm install
```
### 2. Start Dependency Containers (MySQL + SearXNG)
```bash
docker compose up -d
# Wait for MySQL to be ready (about 5 seconds)
```
### 3. Configure Environment Variables
```bash
cp .env.example .env
# Edit .env:
# - ADMIN_PASSWORD: administrator login password (used for initial seed)
# - SESSION_SECRET: session key (generate with openssl rand -hex 32)
```
### 4. Initialize Database
```bash
pnpm db:deploy # Execute migration and create tables
pnpm db:seed # Initialize administrator account
```
### 5. Build Frontend + Start Service
```bash
pnpm web:build # Build management backend SPA
pnpm dev # Start backend (including MCP + REST API + static hosting)
```
Access `http://localhost:3000` to enter the management backend.
### Development Mode (frontend and backend separated with hot reloading)
```bash
# Terminal 1: backend
pnpm dev
# Terminal 2: frontend (Vite dev server, proxy /api to 3000)
pnpm web:dev
# Access http://localhost:5173
```
## Usage Process
1. Open `http://localhost:3000` in a browser and log in with `ADMIN_PASSWORD`
2. Create a new Key in "Key Management" (plaintext is only displayed once, save immediately)
3. Configure the Key to the AI tool:
```json
{
"mcpServers": {
"linkseek": {
"url": "http://localhost:3000/mcp",
"headers": { "Authorization": "Bearer YOUR_API_KEY" }
}
}
}
```
4. After the AI tool invokes the tool, view usage in "Request Overview" and "Key Details"
## Verification
```bash
# Health check
curl http://localhost:3000/health
# MCP handshake (replace YOUR_API_KEY)
curl http://localhost:3000/mcp \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}'
```
## Tool Description
| Tool | Function | Key Parameters |
|------|----------|---------------|
| `web_search` | Network search | `query`, `maxResults`, `timeRange`(day/month/year), `language` |
| `web_fetch` | Retrieve webpage content (Markdown) | `url` |
| `web_search_and_fetch` | Search + batch retrieve content | `query`, `fetchCount`, `searchMaxResults` |
## Security Description
- **API Key**: stored as SHA-256 hash in database, plaintext only returned once during creation
- **Administrator password**: stored as argon2id hash
- **SSRF protection**: block RFC1918 private addresses, `169.254.169.254` (cloud metadata), loopback, etc.; custom DNS lookup with fixed resolution results to prevent rebinding; redirect hop-by-hop re-verification
- **SSRF_STRICT**: set to `true` to additionally block `reserved`/`multicast` segments (recommended for production servers; keep `false` for development machines with fake-ip proxy)
## Project Structure
```
├── prisma/ # Database schema + migration + seed
├── src/ # Backend (Node.js + Express + TypeScript)
│ ├── index.ts # Entry: MCP + REST API + static hosting
│ ├── config.ts # Environment variable verification
│ ├── lib/prisma.ts # Prisma client singleton
│ ├── auth/ # Authentication (KeyStore / verifier / session)
│ ├── admin/ # Management REST API (auth/keys/stats routes)
│ ├── tools/ # MCP tool implementation
│ ├── search/ # SearXNG search
│ ├── fetch/ # Webpage retrieval + SSRF protection
│ └── utils/ # Logging + usage recording
├── web/ # Management backend SPA (Vue 3 + Naive UI + Vite)
│ └── src/views/ # Login / overview / Key list / Key details
├── searxng/ # SearXNG configuration
└── docker-compose.yml # MySQL + SearXNG (local development)
```
