@soulike/deepseek-web-mcp 0.0.0 → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +44 -0
- package/dist/index.js +42 -0
- package/dist/presenters/errors.js +100 -0
- package/dist/server.js +11 -0
- package/dist/services/deepseek-client.js +167 -0
- package/dist/tools/fetch.js +72 -0
- package/dist/tools/index.js +6 -0
- package/dist/tools/search.js +152 -0
- package/dist/version.js +14 -0
- package/package.json +27 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Soulike
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# `@soulike/deepseek-web-mcp`
|
|
2
|
+
|
|
3
|
+
MCP server exposing [DeepSeek Web Search and Fetch APIs](https://api-docs.deepseek.com/zh-cn/guides/search.md) over stdio transport.
|
|
4
|
+
|
|
5
|
+
## Requirements
|
|
6
|
+
|
|
7
|
+
- Node.js `>=24`
|
|
8
|
+
- A DeepSeek API key set in `DEEPSEEK_API_KEY`
|
|
9
|
+
|
|
10
|
+
## Configuration
|
|
11
|
+
|
|
12
|
+
Run directly with `npx`:
|
|
13
|
+
|
|
14
|
+
```json
|
|
15
|
+
{
|
|
16
|
+
"mcpServers": {
|
|
17
|
+
"deepseek-web": {
|
|
18
|
+
"command": "npx",
|
|
19
|
+
"args": ["-y", "@soulike/deepseek-web-mcp"],
|
|
20
|
+
"env": {
|
|
21
|
+
"DEEPSEEK_API_KEY": "your-deepseek-api-key"
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Tools
|
|
29
|
+
|
|
30
|
+
### `deepseek_search`
|
|
31
|
+
|
|
32
|
+
Search the web using `POST https://api.deepseek.com/v1/tools/search`.
|
|
33
|
+
|
|
34
|
+
- `query` (string, required): 1–128 Unicode characters, non-whitespace. Supports `site:`, `-site:`, `-`, `-"..."`, `"..."`, `lang:`, `after:`, and `before:` operators.
|
|
35
|
+
- `count` (integer, optional): Number of results (`1`–`50`, default `10`).
|
|
36
|
+
- `ori_question` (string | null, optional): Original user question (1–128 Unicode characters).
|
|
37
|
+
- `localization` (string, optional): IP address for localized results.
|
|
38
|
+
- `need_content` (boolean, optional): Include full page text in `content` (default `false`).
|
|
39
|
+
|
|
40
|
+
### `deepseek_fetch`
|
|
41
|
+
|
|
42
|
+
Fetch a web page as Markdown using `POST https://api.deepseek.com/v1/tools/fetch`.
|
|
43
|
+
|
|
44
|
+
- `url` (string, required): HTTP/HTTPS URL with a host, max 8192 characters, without embedded username or password.
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { realpathSync } from 'node:fs';
|
|
3
|
+
import { fileURLToPath } from 'node:url';
|
|
4
|
+
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
|
5
|
+
import { createServer } from "./server.js";
|
|
6
|
+
import { createDeepSeekWebClient } from "./services/deepseek-client.js";
|
|
7
|
+
function isEntryPoint(moduleUrl, argv1) {
|
|
8
|
+
if (argv1 === undefined) {
|
|
9
|
+
return false;
|
|
10
|
+
}
|
|
11
|
+
try {
|
|
12
|
+
return realpathSync(argv1) === realpathSync(fileURLToPath(moduleUrl));
|
|
13
|
+
}
|
|
14
|
+
catch {
|
|
15
|
+
return false;
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
async function main() {
|
|
19
|
+
const rawApiKey = process.env['DEEPSEEK_API_KEY'];
|
|
20
|
+
const apiKey = rawApiKey !== undefined && rawApiKey.trim() !== '' ? rawApiKey : undefined;
|
|
21
|
+
const client = apiKey !== undefined ? createDeepSeekWebClient({ apiKey }) : undefined;
|
|
22
|
+
const server = createServer({ client });
|
|
23
|
+
const transport = new StdioServerTransport();
|
|
24
|
+
const shutdown = (signal) => {
|
|
25
|
+
console.error(`Received ${signal}, shutting down deepseek-web-mcp...`);
|
|
26
|
+
server.close().then(() => {
|
|
27
|
+
process.exitCode = 0;
|
|
28
|
+
}, (error) => {
|
|
29
|
+
console.error('Error closing deepseek-web-mcp:', error);
|
|
30
|
+
process.exitCode = 1;
|
|
31
|
+
});
|
|
32
|
+
};
|
|
33
|
+
process.once('SIGINT', shutdown);
|
|
34
|
+
process.once('SIGTERM', shutdown);
|
|
35
|
+
await server.connect(transport);
|
|
36
|
+
}
|
|
37
|
+
if (isEntryPoint(import.meta.url, process.argv[1])) {
|
|
38
|
+
main().catch((error) => {
|
|
39
|
+
console.error('Failed to start deepseek-web-mcp:', error);
|
|
40
|
+
process.exitCode = 1;
|
|
41
|
+
});
|
|
42
|
+
}
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
import { DeepSeekApiError, } from "../services/deepseek-client.js";
|
|
2
|
+
function operationLabel(operation) {
|
|
3
|
+
return operation === 'search' ? 'Search' : 'Fetch';
|
|
4
|
+
}
|
|
5
|
+
function getHttpGuidance(operation, status) {
|
|
6
|
+
if (status === undefined) {
|
|
7
|
+
return 'Do not retry without changing the request.';
|
|
8
|
+
}
|
|
9
|
+
switch (status) {
|
|
10
|
+
case 400:
|
|
11
|
+
case 413:
|
|
12
|
+
return 'Adjust the request parameters and retry.';
|
|
13
|
+
case 401:
|
|
14
|
+
return 'DEEPSEEK_API_KEY is missing or invalid; do not retry until the user fixes credentials.';
|
|
15
|
+
case 402:
|
|
16
|
+
return 'DeepSeek account balance is insufficient; do not retry until the user adds credit.';
|
|
17
|
+
case 403:
|
|
18
|
+
return operation === 'fetch'
|
|
19
|
+
? 'Target URL was rejected by security policy; do not retry this URL—try a different source.'
|
|
20
|
+
: 'Request was forbidden; do not retry unchanged.';
|
|
21
|
+
case 404:
|
|
22
|
+
return operation === 'fetch'
|
|
23
|
+
? 'No extractable Markdown content at this URL (unreachable, blocked, unsupported content type, or empty page); do not retry this URL—try another URL or use search summaries.'
|
|
24
|
+
: 'Resource not found; do not retry unchanged.';
|
|
25
|
+
case 408:
|
|
26
|
+
case 500:
|
|
27
|
+
case 504:
|
|
28
|
+
return 'Transient upstream timeout or server error; safe to retry after a brief pause.';
|
|
29
|
+
case 429:
|
|
30
|
+
return 'Rate limit exceeded; pause briefly and reduce concurrent calls before retrying.';
|
|
31
|
+
default:
|
|
32
|
+
if (status >= 500) {
|
|
33
|
+
return 'Transient upstream server error; safe to retry after a brief pause.';
|
|
34
|
+
}
|
|
35
|
+
return 'Do not retry without changing the request.';
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
function formatDeepSeekApiError(error) {
|
|
39
|
+
const label = operationLabel(error.operation);
|
|
40
|
+
switch (error.kind) {
|
|
41
|
+
case 'timeout':
|
|
42
|
+
return `${error.message}. Safe to retry or try a different query/URL.`;
|
|
43
|
+
case 'invalid_response':
|
|
44
|
+
return `${error.message}. Retry briefly or inspect the upstream response.`;
|
|
45
|
+
case 'http': {
|
|
46
|
+
const guidance = getHttpGuidance(error.operation, error.status);
|
|
47
|
+
const tags = [error.code, error.errorType].filter((value) => value !== undefined && value !== '');
|
|
48
|
+
const tagSuffix = tags.length > 0 ? ` [${tags.join(' / ')}]` : '';
|
|
49
|
+
const statusPart = error.status !== undefined ? `HTTP ${error.status}` : 'HTTP error';
|
|
50
|
+
const detailPart = error.upstreamMessage !== undefined && error.upstreamMessage !== ''
|
|
51
|
+
? `: ${error.upstreamMessage}`
|
|
52
|
+
: '';
|
|
53
|
+
return `DeepSeek ${label} failed (${statusPart}${tagSuffix})${detailPart}. ${guidance}`;
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
export function createMissingApiKeyResult() {
|
|
58
|
+
return {
|
|
59
|
+
content: [
|
|
60
|
+
{
|
|
61
|
+
type: 'text',
|
|
62
|
+
text: 'DEEPSEEK_API_KEY is not set. Configure DEEPSEEK_API_KEY in the MCP server environment and restart the server; do not retry until configured.',
|
|
63
|
+
},
|
|
64
|
+
],
|
|
65
|
+
isError: true,
|
|
66
|
+
};
|
|
67
|
+
}
|
|
68
|
+
function createToolErrorResult(operation, error) {
|
|
69
|
+
if (error instanceof DeepSeekApiError) {
|
|
70
|
+
return {
|
|
71
|
+
content: [{ type: 'text', text: formatDeepSeekApiError(error) }],
|
|
72
|
+
isError: true,
|
|
73
|
+
};
|
|
74
|
+
}
|
|
75
|
+
const label = operationLabel(operation);
|
|
76
|
+
const detail = error instanceof Error ? error.message : String(error);
|
|
77
|
+
return {
|
|
78
|
+
content: [
|
|
79
|
+
{
|
|
80
|
+
type: 'text',
|
|
81
|
+
text: `DeepSeek ${label} failed: ${detail}`,
|
|
82
|
+
},
|
|
83
|
+
],
|
|
84
|
+
isError: true,
|
|
85
|
+
};
|
|
86
|
+
}
|
|
87
|
+
export async function executeWithClient(operation, client, signal, run) {
|
|
88
|
+
if (client === undefined) {
|
|
89
|
+
return createMissingApiKeyResult();
|
|
90
|
+
}
|
|
91
|
+
try {
|
|
92
|
+
return await run(client);
|
|
93
|
+
}
|
|
94
|
+
catch (error) {
|
|
95
|
+
if (signal.aborted) {
|
|
96
|
+
throw error;
|
|
97
|
+
}
|
|
98
|
+
return createToolErrorResult(operation, error);
|
|
99
|
+
}
|
|
100
|
+
}
|
package/dist/server.js
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
2
|
+
import { registerTools } from "./tools/index.js";
|
|
3
|
+
import { SERVER_VERSION } from "./version.js";
|
|
4
|
+
export function createServer(deps) {
|
|
5
|
+
const server = new McpServer({
|
|
6
|
+
name: 'deepseek-web-mcp',
|
|
7
|
+
version: SERVER_VERSION,
|
|
8
|
+
});
|
|
9
|
+
registerTools(server, deps?.client);
|
|
10
|
+
return server;
|
|
11
|
+
}
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
const DEEPSEEK_API_BASE_URL = 'https://api.deepseek.com';
|
|
3
|
+
const REQUEST_TIMEOUT_MS = 60_000;
|
|
4
|
+
const searchResultWireSchema = z.object({
|
|
5
|
+
rerank_score: z.number(),
|
|
6
|
+
title: z.string(),
|
|
7
|
+
url: z.string(),
|
|
8
|
+
snippet: z.string(),
|
|
9
|
+
summary: z.string(),
|
|
10
|
+
content: z.string(),
|
|
11
|
+
site_name: z.string().nullable(),
|
|
12
|
+
site_icon: z.string().nullable(),
|
|
13
|
+
date: z.string().nullable(),
|
|
14
|
+
authority: z.number().int(),
|
|
15
|
+
});
|
|
16
|
+
const searchResponseWireSchema = z.object({
|
|
17
|
+
results: z.array(searchResultWireSchema),
|
|
18
|
+
});
|
|
19
|
+
const fetchResponseWireSchema = z.object({
|
|
20
|
+
title: z.string(),
|
|
21
|
+
content: z.string(),
|
|
22
|
+
});
|
|
23
|
+
const deepSeekErrorWireSchema = z.object({
|
|
24
|
+
error: z.object({
|
|
25
|
+
message: z.string(),
|
|
26
|
+
type: z.string().optional(),
|
|
27
|
+
param: z.unknown().optional(),
|
|
28
|
+
code: z.string().nullable().optional(),
|
|
29
|
+
}),
|
|
30
|
+
});
|
|
31
|
+
export class DeepSeekApiError extends Error {
|
|
32
|
+
operation;
|
|
33
|
+
kind;
|
|
34
|
+
status;
|
|
35
|
+
code;
|
|
36
|
+
errorType;
|
|
37
|
+
upstreamMessage;
|
|
38
|
+
constructor(details) {
|
|
39
|
+
super(details.message, details.cause !== undefined ? { cause: details.cause } : undefined);
|
|
40
|
+
this.name = 'DeepSeekApiError';
|
|
41
|
+
this.operation = details.operation;
|
|
42
|
+
this.kind = details.kind;
|
|
43
|
+
this.status = details.status;
|
|
44
|
+
this.code = details.code;
|
|
45
|
+
this.errorType = details.errorType;
|
|
46
|
+
this.upstreamMessage = details.upstreamMessage;
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
function isTimeoutError(error) {
|
|
50
|
+
return error instanceof Error && error.name === 'TimeoutError';
|
|
51
|
+
}
|
|
52
|
+
function createTimeoutError(operation, timeoutMs, cause) {
|
|
53
|
+
return new DeepSeekApiError({
|
|
54
|
+
operation,
|
|
55
|
+
kind: 'timeout',
|
|
56
|
+
message: `DeepSeek ${operation} request timed out after ${timeoutMs / 1000}s`,
|
|
57
|
+
cause,
|
|
58
|
+
});
|
|
59
|
+
}
|
|
60
|
+
async function parseHttpError(operation, timeoutMs, response) {
|
|
61
|
+
let rawBody;
|
|
62
|
+
try {
|
|
63
|
+
rawBody = (await response.text()).trim();
|
|
64
|
+
}
|
|
65
|
+
catch (error) {
|
|
66
|
+
if (isTimeoutError(error)) {
|
|
67
|
+
return createTimeoutError(operation, timeoutMs, error);
|
|
68
|
+
}
|
|
69
|
+
throw error;
|
|
70
|
+
}
|
|
71
|
+
if (rawBody !== '') {
|
|
72
|
+
try {
|
|
73
|
+
const parsedJson = JSON.parse(rawBody);
|
|
74
|
+
const parsedError = deepSeekErrorWireSchema.safeParse(parsedJson);
|
|
75
|
+
if (parsedError.success) {
|
|
76
|
+
const { message, type, code } = parsedError.data.error;
|
|
77
|
+
return new DeepSeekApiError({
|
|
78
|
+
operation,
|
|
79
|
+
kind: 'http',
|
|
80
|
+
status: response.status,
|
|
81
|
+
code: code !== undefined && code !== null && code !== ''
|
|
82
|
+
? code
|
|
83
|
+
: undefined,
|
|
84
|
+
errorType: type !== undefined && type !== '' ? type : undefined,
|
|
85
|
+
upstreamMessage: message,
|
|
86
|
+
message: `DeepSeek ${operation} failed with HTTP ${response.status}: ${message}`,
|
|
87
|
+
});
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
catch {
|
|
91
|
+
// Non-JSON error bodies fall through to raw text diagnostics.
|
|
92
|
+
}
|
|
93
|
+
return new DeepSeekApiError({
|
|
94
|
+
operation,
|
|
95
|
+
kind: 'http',
|
|
96
|
+
status: response.status,
|
|
97
|
+
upstreamMessage: rawBody,
|
|
98
|
+
message: `DeepSeek ${operation} failed with HTTP ${response.status}: ${rawBody}`,
|
|
99
|
+
});
|
|
100
|
+
}
|
|
101
|
+
return new DeepSeekApiError({
|
|
102
|
+
operation,
|
|
103
|
+
kind: 'http',
|
|
104
|
+
status: response.status,
|
|
105
|
+
message: `DeepSeek ${operation} failed with HTTP ${response.status}`,
|
|
106
|
+
});
|
|
107
|
+
}
|
|
108
|
+
export function createDeepSeekWebClient(options) {
|
|
109
|
+
const fetchFn = options.fetchFn ?? globalThis.fetch;
|
|
110
|
+
const timeoutMs = options.timeoutMs ?? REQUEST_TIMEOUT_MS;
|
|
111
|
+
async function post(operation, path, payload, schema, signal) {
|
|
112
|
+
let response;
|
|
113
|
+
try {
|
|
114
|
+
response = await fetchFn(`${DEEPSEEK_API_BASE_URL}${path}`, {
|
|
115
|
+
method: 'POST',
|
|
116
|
+
headers: {
|
|
117
|
+
Authorization: `Bearer ${options.apiKey}`,
|
|
118
|
+
'Content-Type': 'application/json',
|
|
119
|
+
},
|
|
120
|
+
body: JSON.stringify(payload),
|
|
121
|
+
signal: AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]),
|
|
122
|
+
});
|
|
123
|
+
}
|
|
124
|
+
catch (error) {
|
|
125
|
+
if (isTimeoutError(error)) {
|
|
126
|
+
throw createTimeoutError(operation, timeoutMs, error);
|
|
127
|
+
}
|
|
128
|
+
throw error;
|
|
129
|
+
}
|
|
130
|
+
if (!response.ok) {
|
|
131
|
+
throw await parseHttpError(operation, timeoutMs, response);
|
|
132
|
+
}
|
|
133
|
+
let rawJson;
|
|
134
|
+
try {
|
|
135
|
+
rawJson = await response.json();
|
|
136
|
+
}
|
|
137
|
+
catch (error) {
|
|
138
|
+
if (isTimeoutError(error)) {
|
|
139
|
+
throw createTimeoutError(operation, timeoutMs, error);
|
|
140
|
+
}
|
|
141
|
+
throw new DeepSeekApiError({
|
|
142
|
+
operation,
|
|
143
|
+
kind: 'invalid_response',
|
|
144
|
+
message: `DeepSeek ${operation} returned invalid JSON`,
|
|
145
|
+
cause: error,
|
|
146
|
+
});
|
|
147
|
+
}
|
|
148
|
+
const parsed = schema.safeParse(rawJson);
|
|
149
|
+
if (!parsed.success) {
|
|
150
|
+
throw new DeepSeekApiError({
|
|
151
|
+
operation,
|
|
152
|
+
kind: 'invalid_response',
|
|
153
|
+
message: `DeepSeek ${operation} returned an unexpected response shape: ${parsed.error.message}`,
|
|
154
|
+
cause: parsed.error,
|
|
155
|
+
});
|
|
156
|
+
}
|
|
157
|
+
return parsed.data;
|
|
158
|
+
}
|
|
159
|
+
return {
|
|
160
|
+
search(payload, signal) {
|
|
161
|
+
return post('search', '/v1/tools/search', payload, searchResponseWireSchema, signal);
|
|
162
|
+
},
|
|
163
|
+
fetch(payload, signal) {
|
|
164
|
+
return post('fetch', '/v1/tools/fetch', payload, fetchResponseWireSchema, signal);
|
|
165
|
+
},
|
|
166
|
+
};
|
|
167
|
+
}
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
import { executeWithClient } from "../presenters/errors.js";
|
|
3
|
+
const MAX_FETCH_URL_LENGTH = 8192;
|
|
4
|
+
const FETCH_DESCRIPTION = [
|
|
5
|
+
'Fetch a single public web page and extract its content as Markdown.',
|
|
6
|
+
'Use when you already have a concrete `http://` or `https://` URL (from the user or a `deepseek_search` result) and need the full page text rather than a search summary.',
|
|
7
|
+
'Limitations: fetches one public page per call; cannot log into authenticated/paywalled pages, read binary files, or bypass sites that block automated access (which fail with HTTP 403 or 404).',
|
|
8
|
+
].join(' ');
|
|
9
|
+
function isValidFetchUrl(value) {
|
|
10
|
+
let parsed;
|
|
11
|
+
try {
|
|
12
|
+
parsed = new URL(value);
|
|
13
|
+
}
|
|
14
|
+
catch {
|
|
15
|
+
return false;
|
|
16
|
+
}
|
|
17
|
+
return ((parsed.protocol === 'http:' || parsed.protocol === 'https:') &&
|
|
18
|
+
parsed.hostname !== '' &&
|
|
19
|
+
parsed.username === '' &&
|
|
20
|
+
parsed.password === '');
|
|
21
|
+
}
|
|
22
|
+
function formatFetchMarkdown(data) {
|
|
23
|
+
if (data.title === '') {
|
|
24
|
+
return data.content;
|
|
25
|
+
}
|
|
26
|
+
if (data.content === '') {
|
|
27
|
+
return `# ${data.title}`;
|
|
28
|
+
}
|
|
29
|
+
const firstNonEmptyLine = data.content
|
|
30
|
+
.split('\n')
|
|
31
|
+
.find((line) => line.trim() !== '');
|
|
32
|
+
if (firstNonEmptyLine?.trim() === `# ${data.title.trim()}`) {
|
|
33
|
+
return data.content;
|
|
34
|
+
}
|
|
35
|
+
return `# ${data.title}\n\n${data.content}`;
|
|
36
|
+
}
|
|
37
|
+
export function registerFetchTool(server, client) {
|
|
38
|
+
server.registerTool('deepseek_fetch', {
|
|
39
|
+
title: 'Web Page Fetch',
|
|
40
|
+
description: FETCH_DESCRIPTION,
|
|
41
|
+
inputSchema: {
|
|
42
|
+
url: z
|
|
43
|
+
.string()
|
|
44
|
+
.min(1)
|
|
45
|
+
.max(MAX_FETCH_URL_LENGTH)
|
|
46
|
+
.refine(isValidFetchUrl, {
|
|
47
|
+
message: 'url must be a public http:// or https:// URL with a host and no embedded username or password, e.g. "https://example.com/article".',
|
|
48
|
+
})
|
|
49
|
+
.describe('Public http:// or https:// URL with a host and no credentials (max 8192 characters), e.g. "https://example.com/article".'),
|
|
50
|
+
},
|
|
51
|
+
outputSchema: {
|
|
52
|
+
title: z.string().describe('Extracted page title, or empty string.'),
|
|
53
|
+
content: z.string().describe('Extracted page body in Markdown.'),
|
|
54
|
+
},
|
|
55
|
+
annotations: {
|
|
56
|
+
readOnlyHint: true,
|
|
57
|
+
idempotentHint: false,
|
|
58
|
+
openWorldHint: true,
|
|
59
|
+
},
|
|
60
|
+
}, (args, extra) => executeWithClient('fetch', client, extra.signal, async (activeClient) => {
|
|
61
|
+
const data = await activeClient.fetch({ url: args.url }, extra.signal);
|
|
62
|
+
return {
|
|
63
|
+
content: [
|
|
64
|
+
{
|
|
65
|
+
type: 'text',
|
|
66
|
+
text: formatFetchMarkdown(data),
|
|
67
|
+
},
|
|
68
|
+
],
|
|
69
|
+
structuredContent: data,
|
|
70
|
+
};
|
|
71
|
+
}));
|
|
72
|
+
}
|
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
import { executeWithClient } from "../presenters/errors.js";
|
|
3
|
+
const MAX_SEARCH_TEXT_CODE_POINTS = 128;
|
|
4
|
+
const SEARCH_DESCRIPTION = [
|
|
5
|
+
'Search live web pages when you need up-to-date information or do not have a specific URL yet.',
|
|
6
|
+
'Returns ranked results with URLs, publish dates, quality/authority scores, and ~600-800 character summaries.',
|
|
7
|
+
'By default full page bodies are omitted (`need_content=false`); prefer reviewing summaries first and calling `deepseek_fetch` on selected URLs rather than enabling `need_content=true` across many results.',
|
|
8
|
+
'Limitations: text web search only—does not support image search.',
|
|
9
|
+
'Query operators: join multiple `site:` filters with `OR` (`site:a.com OR site:b.com`); separate `-site:`, `-term`, `-"phrase"`, and `"exact phrase"` with spaces; use comma-separated language codes (`lang:zh,en`); and use `after:YYYY` / `after:YYYY-MM-DD` or `before:YYYY` / `before:YYYY-MM-DD` for date bounds.',
|
|
10
|
+
].join(' ');
|
|
11
|
+
const searchOutputResultSchema = z.object({
|
|
12
|
+
rerank_score: z
|
|
13
|
+
.number()
|
|
14
|
+
.describe('Relevance and quality score from 0 to 3 (>= 1.5 indicates a high-quality result).'),
|
|
15
|
+
title: z.string().describe('Result page title.'),
|
|
16
|
+
url: z.string().describe('Result page URL.'),
|
|
17
|
+
snippet: z
|
|
18
|
+
.string()
|
|
19
|
+
.describe('Short excerpt (~100-200 characters) for brief previews.'),
|
|
20
|
+
summary: z
|
|
21
|
+
.string()
|
|
22
|
+
.describe('Longer query-focused summary (~600-800 characters) suited for LLM reading.'),
|
|
23
|
+
content: z
|
|
24
|
+
.string()
|
|
25
|
+
.describe('Full extracted page body; empty string when need_content is false or unavailable.'),
|
|
26
|
+
site_name: z
|
|
27
|
+
.string()
|
|
28
|
+
.nullable()
|
|
29
|
+
.describe('Publisher or site name, or null if unknown.'),
|
|
30
|
+
site_icon: z
|
|
31
|
+
.string()
|
|
32
|
+
.nullable()
|
|
33
|
+
.describe('Site favicon URL, or null if unknown.'),
|
|
34
|
+
date: z
|
|
35
|
+
.string()
|
|
36
|
+
.nullable()
|
|
37
|
+
.describe('Publication timestamp in UTC RFC 3339 format, or null.'),
|
|
38
|
+
authority: z
|
|
39
|
+
.number()
|
|
40
|
+
.int()
|
|
41
|
+
.describe('Source authority score from 0 to 4 (>= 3 is highly authoritative; -1 means unknown).'),
|
|
42
|
+
});
|
|
43
|
+
function codePointLength(value) {
|
|
44
|
+
return [...value].length;
|
|
45
|
+
}
|
|
46
|
+
function formatSearchResult(result, index) {
|
|
47
|
+
const lines = [
|
|
48
|
+
`## ${index + 1}. ${result.title || '(Untitled)'}`,
|
|
49
|
+
`- URL: ${result.url}`,
|
|
50
|
+
];
|
|
51
|
+
const metadata = [];
|
|
52
|
+
if (result.site_name !== null && result.site_name !== '') {
|
|
53
|
+
metadata.push(`Site: ${result.site_name}`);
|
|
54
|
+
}
|
|
55
|
+
if (result.date !== null && result.date !== '') {
|
|
56
|
+
metadata.push(`Date: ${result.date}`);
|
|
57
|
+
}
|
|
58
|
+
metadata.push(`Score: ${result.rerank_score}/3`);
|
|
59
|
+
if (result.authority >= 0) {
|
|
60
|
+
metadata.push(`Authority: ${result.authority}/4`);
|
|
61
|
+
}
|
|
62
|
+
lines.push(`- ${metadata.join(' | ')}`);
|
|
63
|
+
const overview = result.summary !== '' ? result.summary : result.snippet;
|
|
64
|
+
if (overview !== '') {
|
|
65
|
+
lines.push('', overview);
|
|
66
|
+
}
|
|
67
|
+
if (result.content !== '') {
|
|
68
|
+
lines.push('', '### Content', '', result.content);
|
|
69
|
+
}
|
|
70
|
+
return lines.join('\n');
|
|
71
|
+
}
|
|
72
|
+
function formatSearchMarkdown(query, data) {
|
|
73
|
+
if (data.results.length === 0) {
|
|
74
|
+
return `No results found for "${query}". Try broadening the keywords or removing restrictive site:/date/language operators.`;
|
|
75
|
+
}
|
|
76
|
+
return data.results.map(formatSearchResult).join('\n\n---\n\n');
|
|
77
|
+
}
|
|
78
|
+
export function registerSearchTool(server, client) {
|
|
79
|
+
server.registerTool('deepseek_search', {
|
|
80
|
+
title: 'Web Search',
|
|
81
|
+
description: SEARCH_DESCRIPTION,
|
|
82
|
+
inputSchema: {
|
|
83
|
+
query: z
|
|
84
|
+
.string()
|
|
85
|
+
.min(1, 'query cannot be empty. Provide 1-128 Unicode characters.')
|
|
86
|
+
.refine((value) => value.trim().length > 0, {
|
|
87
|
+
message: 'query cannot be only whitespace. Provide search terms (1-128 Unicode characters), e.g. "TypeScript release notes".',
|
|
88
|
+
})
|
|
89
|
+
.refine((value) => codePointLength(value) <= MAX_SEARCH_TEXT_CODE_POINTS, {
|
|
90
|
+
message: `query must be at most ${MAX_SEARCH_TEXT_CODE_POINTS} Unicode characters; shorten the query or remove extra modifiers.`,
|
|
91
|
+
})
|
|
92
|
+
.describe('Search query (1-128 Unicode characters, not all whitespace), e.g. \'"release notes" site:github.com after:2025-01-01\'. Keep focused and do not append unnecessary year tokens unless filtering by time.'),
|
|
93
|
+
count: z
|
|
94
|
+
.number()
|
|
95
|
+
.int()
|
|
96
|
+
.min(1)
|
|
97
|
+
.max(50)
|
|
98
|
+
.optional()
|
|
99
|
+
.describe('Number of results to return (integer 1-50, default 10). Use a smaller count (e.g. 5) when need_content is true to avoid context bloat.'),
|
|
100
|
+
ori_question: z
|
|
101
|
+
.string()
|
|
102
|
+
.min(1)
|
|
103
|
+
.refine((value) => codePointLength(value) <= MAX_SEARCH_TEXT_CODE_POINTS, {
|
|
104
|
+
message: `ori_question must be at most ${MAX_SEARCH_TEXT_CODE_POINTS} Unicode characters; summarize concisely or omit it.`,
|
|
105
|
+
})
|
|
106
|
+
.nullable()
|
|
107
|
+
.optional()
|
|
108
|
+
.describe('Optional original natural-language user question (1-128 Unicode characters, or null) when query has been distilled into keywords/operators, to improve intent ranking.'),
|
|
109
|
+
localization: z
|
|
110
|
+
.string()
|
|
111
|
+
.optional()
|
|
112
|
+
.describe('Optional client IP address (e.g. "203.0.113.10") for region-localized results. Omit unless a real user/client IP is known; never invent an IP.'),
|
|
113
|
+
need_content: z
|
|
114
|
+
.boolean()
|
|
115
|
+
.optional()
|
|
116
|
+
.describe('Include full page body in each result (default false). Leave false when summaries suffice or when fetching only selected URLs with deepseek_fetch.'),
|
|
117
|
+
},
|
|
118
|
+
outputSchema: {
|
|
119
|
+
results: z
|
|
120
|
+
.array(searchOutputResultSchema)
|
|
121
|
+
.describe('Ordered search results (empty array when nothing matches).'),
|
|
122
|
+
},
|
|
123
|
+
annotations: {
|
|
124
|
+
readOnlyHint: true,
|
|
125
|
+
idempotentHint: false,
|
|
126
|
+
openWorldHint: true,
|
|
127
|
+
},
|
|
128
|
+
}, (args, extra) => executeWithClient('search', client, extra.signal, async (activeClient) => {
|
|
129
|
+
const data = await activeClient.search({
|
|
130
|
+
query: args.query,
|
|
131
|
+
...(args.count !== undefined ? { count: args.count } : {}),
|
|
132
|
+
...(args.ori_question !== undefined
|
|
133
|
+
? { ori_question: args.ori_question }
|
|
134
|
+
: {}),
|
|
135
|
+
...(args.localization !== undefined
|
|
136
|
+
? { localization: args.localization }
|
|
137
|
+
: {}),
|
|
138
|
+
...(args.need_content !== undefined
|
|
139
|
+
? { need_content: args.need_content }
|
|
140
|
+
: {}),
|
|
141
|
+
}, extra.signal);
|
|
142
|
+
return {
|
|
143
|
+
content: [
|
|
144
|
+
{
|
|
145
|
+
type: 'text',
|
|
146
|
+
text: formatSearchMarkdown(args.query, data),
|
|
147
|
+
},
|
|
148
|
+
],
|
|
149
|
+
structuredContent: data,
|
|
150
|
+
};
|
|
151
|
+
}));
|
|
152
|
+
}
|
package/dist/version.js
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import { readFileSync } from 'node:fs';
|
|
2
|
+
function readPackageVersion() {
|
|
3
|
+
const packageJsonUrl = new URL('../package.json', import.meta.url);
|
|
4
|
+
const parsed = JSON.parse(readFileSync(packageJsonUrl, 'utf8'));
|
|
5
|
+
if (typeof parsed !== 'object' ||
|
|
6
|
+
parsed === null ||
|
|
7
|
+
!('version' in parsed) ||
|
|
8
|
+
typeof parsed.version !== 'string' ||
|
|
9
|
+
parsed.version === '') {
|
|
10
|
+
throw new Error(`Expected non-empty "version" string in ${packageJsonUrl.href}`);
|
|
11
|
+
}
|
|
12
|
+
return parsed.version;
|
|
13
|
+
}
|
|
14
|
+
export const SERVER_VERSION = readPackageVersion();
|
package/package.json
CHANGED
|
@@ -1,11 +1,35 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@soulike/deepseek-web-mcp",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "MCP server for DeepSeek web search and fetch APIs",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
8
8
|
"url": "git+https://github.com/Soulike/mcp.git",
|
|
9
9
|
"directory": "servers/deepseek-web-mcp"
|
|
10
|
+
},
|
|
11
|
+
"type": "module",
|
|
12
|
+
"engines": {
|
|
13
|
+
"node": ">=24"
|
|
14
|
+
},
|
|
15
|
+
"bin": {
|
|
16
|
+
"deepseek-web-mcp": "./dist/index.js"
|
|
17
|
+
},
|
|
18
|
+
"files": [
|
|
19
|
+
"dist"
|
|
20
|
+
],
|
|
21
|
+
"dependencies": {
|
|
22
|
+
"@modelcontextprotocol/sdk": "^1.32.2",
|
|
23
|
+
"zod": "^4.6.7"
|
|
24
|
+
},
|
|
25
|
+
"devDependencies": {
|
|
26
|
+
"@repo/tsconfig": "0.0.0",
|
|
27
|
+
"@types/node": "^24.19.2",
|
|
28
|
+
"typescript": "~6.0.3"
|
|
29
|
+
},
|
|
30
|
+
"scripts": {
|
|
31
|
+
"build": "tsc -p tsconfig.build.json",
|
|
32
|
+
"typecheck": "tsc --noEmit",
|
|
33
|
+
"test": "node --test \"src/**/*.test.ts\""
|
|
10
34
|
}
|
|
11
|
-
}
|
|
35
|
+
}
|