mcp-server-knowledgebase 0.2.0__tar.gz
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.
- mcp_server_knowledgebase-0.2.0/.gitignore +9 -0
- mcp_server_knowledgebase-0.2.0/.python-version +1 -0
- mcp_server_knowledgebase-0.2.0/PKG-INFO +248 -0
- mcp_server_knowledgebase-0.2.0/README.md +237 -0
- mcp_server_knowledgebase-0.2.0/README_zh.md +191 -0
- mcp_server_knowledgebase-0.2.0/pyproject.toml +19 -0
- mcp_server_knowledgebase-0.2.0/src/mcp_server_knowledgebase/__init__.py +1 -0
- mcp_server_knowledgebase-0.2.0/src/mcp_server_knowledgebase/common/__init__.py +0 -0
- mcp_server_knowledgebase-0.2.0/src/mcp_server_knowledgebase/common/auth.py +53 -0
- mcp_server_knowledgebase-0.2.0/src/mcp_server_knowledgebase/config.py +57 -0
- mcp_server_knowledgebase-0.2.0/src/mcp_server_knowledgebase/models.py +66 -0
- mcp_server_knowledgebase-0.2.0/src/mcp_server_knowledgebase/server.py +421 -0
- mcp_server_knowledgebase-0.2.0/uv.lock +1795 -0
|
@@ -0,0 +1 @@
|
|
|
1
|
+
3.13
|
|
@@ -0,0 +1,248 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: mcp-server-knowledgebase
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: MCP server for Viking Knowledge Base Service
|
|
5
|
+
License: MIT
|
|
6
|
+
Requires-Python: >=3.10
|
|
7
|
+
Requires-Dist: aiohttp>=3.11.14
|
|
8
|
+
Requires-Dist: mcp[cli]<3,>=2.1.1
|
|
9
|
+
Requires-Dist: volcengine>=1.0.171
|
|
10
|
+
Description-Content-Type: text/markdown
|
|
11
|
+
|
|
12
|
+
# Viking Knowledge Base MCP Server
|
|
13
|
+
|
|
14
|
+
This MCP server provides a tool to interact with the VolcEngine Viking Knowledge Base Service, allowing you to search and retrieve knowledge from your collections, meanwhile,
|
|
15
|
+
allowing you to add doc to your collections and get doc processing info by doc_id.
|
|
16
|
+
|
|
17
|
+
## Features
|
|
18
|
+
|
|
19
|
+
- Search knowledge based on queries with customizable parameters
|
|
20
|
+
|
|
21
|
+
## Setup
|
|
22
|
+
|
|
23
|
+
### Prerequisites
|
|
24
|
+
|
|
25
|
+
- Python 3.10 or higher
|
|
26
|
+
- A Viking Knowledge Base API key or VolcEngine AK/SK credentials
|
|
27
|
+
|
|
28
|
+
### Installation
|
|
29
|
+
|
|
30
|
+
1. Install the package:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
pip install -e .
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Or with uv (recommended):
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
uv pip install -e .
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### Configuration
|
|
43
|
+
|
|
44
|
+
The server requires at least one authentication method:
|
|
45
|
+
|
|
46
|
+
- API key: set `VIKING_API_KEY`. Requests use
|
|
47
|
+
`Authorization: Bearer <VIKING_API_KEY>`.
|
|
48
|
+
- AK/SK: set both `VOLCENGINE_ACCESS_KEY` and `VOLCENGINE_SECRET_KEY`.
|
|
49
|
+
Requests use VolcEngine SignerV4 authentication.
|
|
50
|
+
|
|
51
|
+
When both methods are configured, `VIKING_API_KEY` takes precedence and AK/SK
|
|
52
|
+
is ignored. When no API key is configured, AK and SK must be provided together.
|
|
53
|
+
The server rejects configurations with no usable authentication method.
|
|
54
|
+
|
|
55
|
+
Optional environment variables:
|
|
56
|
+
- `KNOWLEDGE_BASE_PROJECT`: Viking Knowledge Base project name (default: `default`)
|
|
57
|
+
- `KNOWLEDGE_BASE_REGION`: Viking Knowledge Base region (default: `cn-north-1`)
|
|
58
|
+
- `MCP_SERVER_HOST`: Streamable HTTP bind host (default: `127.0.0.1`)
|
|
59
|
+
- `MCP_SERVER_PORT`: Streamable HTTP port; falls back to `PORT` (default: `8000`)
|
|
60
|
+
- `STREAMABLE_HTTP_PATH`: Streamable HTTP endpoint path (default: `/mcp`)
|
|
61
|
+
- `KNOWLEDGE_BASE_TIMEOUT`: Upstream request timeout in seconds (default: `30`)
|
|
62
|
+
|
|
63
|
+
## Usage
|
|
64
|
+
|
|
65
|
+
### Running the Server
|
|
66
|
+
|
|
67
|
+
The server supports stdio for local integrations and stateless Streamable HTTP
|
|
68
|
+
for remote deployments:
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
python -m mcp_server_knowledgebase.server --transport stdio
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Or:
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
python -m mcp_server_knowledgebase.server --transport streamable-http
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
The Streamable HTTP endpoint is `http://127.0.0.1:8000/mcp` by default.
|
|
81
|
+
Set `MCP_SERVER_HOST=0.0.0.0` when running behind a trusted gateway.
|
|
82
|
+
|
|
83
|
+
### MCP protocol compatibility
|
|
84
|
+
|
|
85
|
+
This server uses MCP Python SDK 2.x and speaks protocol revision `2026-07-28`.
|
|
86
|
+
Modern clients use the stateless per-request protocol and `server/discover`;
|
|
87
|
+
the same process also supports older handshake-based clients automatically.
|
|
88
|
+
Legacy HTTP+SSE is intentionally not exposed because it is deprecated by the
|
|
89
|
+
`2026-07-28` specification.
|
|
90
|
+
|
|
91
|
+
The HTTP endpoint does not turn the configured API key or VolcEngine AK/SK into
|
|
92
|
+
client authentication. Protect remote deployments with an authentication
|
|
93
|
+
gateway or MCP-compatible OAuth, and never expose the service credentials to
|
|
94
|
+
callers.
|
|
95
|
+
|
|
96
|
+
### Available Tools
|
|
97
|
+
|
|
98
|
+
#### add_doc
|
|
99
|
+
|
|
100
|
+
Add a document to a collection in your project.
|
|
101
|
+
|
|
102
|
+
```python
|
|
103
|
+
add_doc(
|
|
104
|
+
collection_name="collection_name",
|
|
105
|
+
add_type="url",
|
|
106
|
+
doc_id="mcp_server_auto_gen_doc_id_xxxxxxx",
|
|
107
|
+
doc_name="doc_xxxx",
|
|
108
|
+
doc_type="pdf",
|
|
109
|
+
url="http://xxxxx.pdf"
|
|
110
|
+
)
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Parameters:
|
|
114
|
+
- `collection_name` (required): the name of the collection you want to add document .
|
|
115
|
+
- `add_type` (required): the type of the document to add. so far only support "url" now.
|
|
116
|
+
- `doc_id` (required): you should generate a unique doc_id based on user's given url and timestamp, the doc_id can only use English letters, numbers, and underscores , and must start with an English letter. It cannot be empty. Length requirement: [1, 128], you can use a format like "mcp_server_auto_gen_doc_id_xxxxxxx".
|
|
117
|
+
- `doc_name` (required): the name of the document to add. You can generate a unique doc_name based on the user-provided URL and timestamp. The length of doc_name must be between 1 and 256; for example, "mcp_server_auto_gen_doc_name_xxxxxxx".
|
|
118
|
+
- `doc_type` (required): the type of the document to add. for structured document, we support xlsx, csv,jsonl, for unstructured document, wu support txt, doc, docx, pdf, markdown, faq.xlsx, pptx". you should judge the doc_type based on user's given url and judge if we support this doc type. if supported, assign this parameter.
|
|
119
|
+
- `url` (required): the url of the document to add. user should give a valid url, we will add the doc to the collection.
|
|
120
|
+
|
|
121
|
+
#### get_doc
|
|
122
|
+
|
|
123
|
+
Get information about document by collection_name and doc_id .
|
|
124
|
+
|
|
125
|
+
```python
|
|
126
|
+
get_doc(
|
|
127
|
+
collection_name="collection_name",
|
|
128
|
+
doc_id="mcp_server_auto_gen_doc_id_xxxxxxx",
|
|
129
|
+
)
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Parameters:
|
|
133
|
+
- `collection_name` (required): the name of the collection you want to get information .
|
|
134
|
+
- `doc_id` (required): the doc_id of document user want to get information .
|
|
135
|
+
|
|
136
|
+
#### get_collection
|
|
137
|
+
|
|
138
|
+
Get information about a viking knowledge base collection from your project .
|
|
139
|
+
|
|
140
|
+
```python
|
|
141
|
+
get_collection(
|
|
142
|
+
collection_name="collection_name",
|
|
143
|
+
)
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Parameters:
|
|
147
|
+
- `collection_name` (required): the name of the collection you want to get information .
|
|
148
|
+
|
|
149
|
+
|
|
150
|
+
#### list_collections
|
|
151
|
+
|
|
152
|
+
List all knowledge base collections of the globally configured project .
|
|
153
|
+
|
|
154
|
+
```python
|
|
155
|
+
list_collections(
|
|
156
|
+
)
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
#### search_knowledge
|
|
161
|
+
|
|
162
|
+
Search for knowledge in the configured collection based on a query.
|
|
163
|
+
|
|
164
|
+
```python
|
|
165
|
+
search_knowledge(
|
|
166
|
+
query="How to reset my password?",
|
|
167
|
+
limit=3,
|
|
168
|
+
collection_name="collection_name",
|
|
169
|
+
doc_filter=None,
|
|
170
|
+
)
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
Parameters:
|
|
174
|
+
- `query` (required): The search query string
|
|
175
|
+
- `limit` (optional): Maximum number of results to return, from 1 to 100 (default: 3)
|
|
176
|
+
- `collection_name` (required): Knowledge Base collection name to search
|
|
177
|
+
- `doc_filter` (optional): the filter is used to filter search results(default: None), which is structured as a JSON object with the following key components:
|
|
178
|
+
- `op` (string, required): specifies the query operator that defines the filtering logic. Valid values are 'must' and 'must_not', 'must' means results must satisfy the condition (inclusion filter),'must_not' means results must not satisfy the condition (exclusion filter).
|
|
179
|
+
- `field` (string, required): indicates the specific document field to apply the filter on (e.g., "doc_id").
|
|
180
|
+
- `conds` (array, required): contains the concrete values used for filtering. The data type of elements in the array depends on the field.
|
|
181
|
+
|
|
182
|
+
Each result contains the chunk `id` and `content`, plus the source document's
|
|
183
|
+
`doc_id` and `doc_name`. The metadata fields are `null` when Viking does not
|
|
184
|
+
provide them. A non-null `doc_id` can be passed directly to `get_doc`.
|
|
185
|
+
|
|
186
|
+
## MCP Integration
|
|
187
|
+
|
|
188
|
+
To add this server to your MCP configuration, add the following to your MCP settings file:
|
|
189
|
+
|
|
190
|
+
```json
|
|
191
|
+
{
|
|
192
|
+
"mcpServers": {
|
|
193
|
+
"knowledgebase": {
|
|
194
|
+
"command": "uvx",
|
|
195
|
+
"args": [
|
|
196
|
+
"--from",
|
|
197
|
+
"mcp-server-knowledgebase>=0.2.0",
|
|
198
|
+
"mcp-server-knowledgebase"
|
|
199
|
+
],
|
|
200
|
+
"env": {
|
|
201
|
+
"VIKING_API_KEY": "your-viking-api-key",
|
|
202
|
+
"KNOWLEDGE_BASE_PROJECT": "your-project-name",
|
|
203
|
+
"KNOWLEDGE_BASE_REGION": "your-region"
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
You may alternatively or additionally configure both
|
|
211
|
+
`VOLCENGINE_ACCESS_KEY` and `VOLCENGINE_SECRET_KEY`. If all three variables are
|
|
212
|
+
set, `VIKING_API_KEY` takes precedence.
|
|
213
|
+
|
|
214
|
+
## Troubleshooting
|
|
215
|
+
|
|
216
|
+
### Common Issues
|
|
217
|
+
|
|
218
|
+
1. **Authentication Errors**
|
|
219
|
+
- Verify your API key or AK/SK credentials are correct
|
|
220
|
+
- Ensure at least one authentication method is configured
|
|
221
|
+
- Check that you have the necessary permissions for the collection
|
|
222
|
+
|
|
223
|
+
2. **Connection Timeouts**
|
|
224
|
+
- Check your network connection to the VolcEngine API
|
|
225
|
+
- Verify the host configuration is correct
|
|
226
|
+
|
|
227
|
+
3. **Empty Results**
|
|
228
|
+
- Verify the collection name is correct
|
|
229
|
+
- Try broadening your search query
|
|
230
|
+
|
|
231
|
+
### Logging
|
|
232
|
+
|
|
233
|
+
The server uses Python's logging module with INFO level by default. You can see detailed logs in the console when running the server.
|
|
234
|
+
|
|
235
|
+
## Contributing
|
|
236
|
+
|
|
237
|
+
Contributions to improve the Viking Knowledge Base MCP Server are welcome. Please follow these steps:
|
|
238
|
+
|
|
239
|
+
1. Fork the repository
|
|
240
|
+
2. Create a feature branch
|
|
241
|
+
3. Make your changes
|
|
242
|
+
4. Submit a pull request
|
|
243
|
+
|
|
244
|
+
Please ensure your code follows the project's coding standards and includes appropriate tests.
|
|
245
|
+
|
|
246
|
+
## License
|
|
247
|
+
|
|
248
|
+
volcengine/mcp-server is licensed under the [MIT License](https://github.com/volcengine/mcp-server/blob/main/LICENSE).
|
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
# Viking Knowledge Base MCP Server
|
|
2
|
+
|
|
3
|
+
This MCP server provides a tool to interact with the VolcEngine Viking Knowledge Base Service, allowing you to search and retrieve knowledge from your collections, meanwhile,
|
|
4
|
+
allowing you to add doc to your collections and get doc processing info by doc_id.
|
|
5
|
+
|
|
6
|
+
## Features
|
|
7
|
+
|
|
8
|
+
- Search knowledge based on queries with customizable parameters
|
|
9
|
+
|
|
10
|
+
## Setup
|
|
11
|
+
|
|
12
|
+
### Prerequisites
|
|
13
|
+
|
|
14
|
+
- Python 3.10 or higher
|
|
15
|
+
- A Viking Knowledge Base API key or VolcEngine AK/SK credentials
|
|
16
|
+
|
|
17
|
+
### Installation
|
|
18
|
+
|
|
19
|
+
1. Install the package:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
pip install -e .
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Or with uv (recommended):
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
uv pip install -e .
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
### Configuration
|
|
32
|
+
|
|
33
|
+
The server requires at least one authentication method:
|
|
34
|
+
|
|
35
|
+
- API key: set `VIKING_API_KEY`. Requests use
|
|
36
|
+
`Authorization: Bearer <VIKING_API_KEY>`.
|
|
37
|
+
- AK/SK: set both `VOLCENGINE_ACCESS_KEY` and `VOLCENGINE_SECRET_KEY`.
|
|
38
|
+
Requests use VolcEngine SignerV4 authentication.
|
|
39
|
+
|
|
40
|
+
When both methods are configured, `VIKING_API_KEY` takes precedence and AK/SK
|
|
41
|
+
is ignored. When no API key is configured, AK and SK must be provided together.
|
|
42
|
+
The server rejects configurations with no usable authentication method.
|
|
43
|
+
|
|
44
|
+
Optional environment variables:
|
|
45
|
+
- `KNOWLEDGE_BASE_PROJECT`: Viking Knowledge Base project name (default: `default`)
|
|
46
|
+
- `KNOWLEDGE_BASE_REGION`: Viking Knowledge Base region (default: `cn-north-1`)
|
|
47
|
+
- `MCP_SERVER_HOST`: Streamable HTTP bind host (default: `127.0.0.1`)
|
|
48
|
+
- `MCP_SERVER_PORT`: Streamable HTTP port; falls back to `PORT` (default: `8000`)
|
|
49
|
+
- `STREAMABLE_HTTP_PATH`: Streamable HTTP endpoint path (default: `/mcp`)
|
|
50
|
+
- `KNOWLEDGE_BASE_TIMEOUT`: Upstream request timeout in seconds (default: `30`)
|
|
51
|
+
|
|
52
|
+
## Usage
|
|
53
|
+
|
|
54
|
+
### Running the Server
|
|
55
|
+
|
|
56
|
+
The server supports stdio for local integrations and stateless Streamable HTTP
|
|
57
|
+
for remote deployments:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
python -m mcp_server_knowledgebase.server --transport stdio
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Or:
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
python -m mcp_server_knowledgebase.server --transport streamable-http
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
The Streamable HTTP endpoint is `http://127.0.0.1:8000/mcp` by default.
|
|
70
|
+
Set `MCP_SERVER_HOST=0.0.0.0` when running behind a trusted gateway.
|
|
71
|
+
|
|
72
|
+
### MCP protocol compatibility
|
|
73
|
+
|
|
74
|
+
This server uses MCP Python SDK 2.x and speaks protocol revision `2026-07-28`.
|
|
75
|
+
Modern clients use the stateless per-request protocol and `server/discover`;
|
|
76
|
+
the same process also supports older handshake-based clients automatically.
|
|
77
|
+
Legacy HTTP+SSE is intentionally not exposed because it is deprecated by the
|
|
78
|
+
`2026-07-28` specification.
|
|
79
|
+
|
|
80
|
+
The HTTP endpoint does not turn the configured API key or VolcEngine AK/SK into
|
|
81
|
+
client authentication. Protect remote deployments with an authentication
|
|
82
|
+
gateway or MCP-compatible OAuth, and never expose the service credentials to
|
|
83
|
+
callers.
|
|
84
|
+
|
|
85
|
+
### Available Tools
|
|
86
|
+
|
|
87
|
+
#### add_doc
|
|
88
|
+
|
|
89
|
+
Add a document to a collection in your project.
|
|
90
|
+
|
|
91
|
+
```python
|
|
92
|
+
add_doc(
|
|
93
|
+
collection_name="collection_name",
|
|
94
|
+
add_type="url",
|
|
95
|
+
doc_id="mcp_server_auto_gen_doc_id_xxxxxxx",
|
|
96
|
+
doc_name="doc_xxxx",
|
|
97
|
+
doc_type="pdf",
|
|
98
|
+
url="http://xxxxx.pdf"
|
|
99
|
+
)
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Parameters:
|
|
103
|
+
- `collection_name` (required): the name of the collection you want to add document .
|
|
104
|
+
- `add_type` (required): the type of the document to add. so far only support "url" now.
|
|
105
|
+
- `doc_id` (required): you should generate a unique doc_id based on user's given url and timestamp, the doc_id can only use English letters, numbers, and underscores , and must start with an English letter. It cannot be empty. Length requirement: [1, 128], you can use a format like "mcp_server_auto_gen_doc_id_xxxxxxx".
|
|
106
|
+
- `doc_name` (required): the name of the document to add. You can generate a unique doc_name based on the user-provided URL and timestamp. The length of doc_name must be between 1 and 256; for example, "mcp_server_auto_gen_doc_name_xxxxxxx".
|
|
107
|
+
- `doc_type` (required): the type of the document to add. for structured document, we support xlsx, csv,jsonl, for unstructured document, wu support txt, doc, docx, pdf, markdown, faq.xlsx, pptx". you should judge the doc_type based on user's given url and judge if we support this doc type. if supported, assign this parameter.
|
|
108
|
+
- `url` (required): the url of the document to add. user should give a valid url, we will add the doc to the collection.
|
|
109
|
+
|
|
110
|
+
#### get_doc
|
|
111
|
+
|
|
112
|
+
Get information about document by collection_name and doc_id .
|
|
113
|
+
|
|
114
|
+
```python
|
|
115
|
+
get_doc(
|
|
116
|
+
collection_name="collection_name",
|
|
117
|
+
doc_id="mcp_server_auto_gen_doc_id_xxxxxxx",
|
|
118
|
+
)
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Parameters:
|
|
122
|
+
- `collection_name` (required): the name of the collection you want to get information .
|
|
123
|
+
- `doc_id` (required): the doc_id of document user want to get information .
|
|
124
|
+
|
|
125
|
+
#### get_collection
|
|
126
|
+
|
|
127
|
+
Get information about a viking knowledge base collection from your project .
|
|
128
|
+
|
|
129
|
+
```python
|
|
130
|
+
get_collection(
|
|
131
|
+
collection_name="collection_name",
|
|
132
|
+
)
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Parameters:
|
|
136
|
+
- `collection_name` (required): the name of the collection you want to get information .
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
#### list_collections
|
|
140
|
+
|
|
141
|
+
List all knowledge base collections of the globally configured project .
|
|
142
|
+
|
|
143
|
+
```python
|
|
144
|
+
list_collections(
|
|
145
|
+
)
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
#### search_knowledge
|
|
150
|
+
|
|
151
|
+
Search for knowledge in the configured collection based on a query.
|
|
152
|
+
|
|
153
|
+
```python
|
|
154
|
+
search_knowledge(
|
|
155
|
+
query="How to reset my password?",
|
|
156
|
+
limit=3,
|
|
157
|
+
collection_name="collection_name",
|
|
158
|
+
doc_filter=None,
|
|
159
|
+
)
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
Parameters:
|
|
163
|
+
- `query` (required): The search query string
|
|
164
|
+
- `limit` (optional): Maximum number of results to return, from 1 to 100 (default: 3)
|
|
165
|
+
- `collection_name` (required): Knowledge Base collection name to search
|
|
166
|
+
- `doc_filter` (optional): the filter is used to filter search results(default: None), which is structured as a JSON object with the following key components:
|
|
167
|
+
- `op` (string, required): specifies the query operator that defines the filtering logic. Valid values are 'must' and 'must_not', 'must' means results must satisfy the condition (inclusion filter),'must_not' means results must not satisfy the condition (exclusion filter).
|
|
168
|
+
- `field` (string, required): indicates the specific document field to apply the filter on (e.g., "doc_id").
|
|
169
|
+
- `conds` (array, required): contains the concrete values used for filtering. The data type of elements in the array depends on the field.
|
|
170
|
+
|
|
171
|
+
Each result contains the chunk `id` and `content`, plus the source document's
|
|
172
|
+
`doc_id` and `doc_name`. The metadata fields are `null` when Viking does not
|
|
173
|
+
provide them. A non-null `doc_id` can be passed directly to `get_doc`.
|
|
174
|
+
|
|
175
|
+
## MCP Integration
|
|
176
|
+
|
|
177
|
+
To add this server to your MCP configuration, add the following to your MCP settings file:
|
|
178
|
+
|
|
179
|
+
```json
|
|
180
|
+
{
|
|
181
|
+
"mcpServers": {
|
|
182
|
+
"knowledgebase": {
|
|
183
|
+
"command": "uvx",
|
|
184
|
+
"args": [
|
|
185
|
+
"--from",
|
|
186
|
+
"mcp-server-knowledgebase>=0.2.0",
|
|
187
|
+
"mcp-server-knowledgebase"
|
|
188
|
+
],
|
|
189
|
+
"env": {
|
|
190
|
+
"VIKING_API_KEY": "your-viking-api-key",
|
|
191
|
+
"KNOWLEDGE_BASE_PROJECT": "your-project-name",
|
|
192
|
+
"KNOWLEDGE_BASE_REGION": "your-region"
|
|
193
|
+
}
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
}
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
You may alternatively or additionally configure both
|
|
200
|
+
`VOLCENGINE_ACCESS_KEY` and `VOLCENGINE_SECRET_KEY`. If all three variables are
|
|
201
|
+
set, `VIKING_API_KEY` takes precedence.
|
|
202
|
+
|
|
203
|
+
## Troubleshooting
|
|
204
|
+
|
|
205
|
+
### Common Issues
|
|
206
|
+
|
|
207
|
+
1. **Authentication Errors**
|
|
208
|
+
- Verify your API key or AK/SK credentials are correct
|
|
209
|
+
- Ensure at least one authentication method is configured
|
|
210
|
+
- Check that you have the necessary permissions for the collection
|
|
211
|
+
|
|
212
|
+
2. **Connection Timeouts**
|
|
213
|
+
- Check your network connection to the VolcEngine API
|
|
214
|
+
- Verify the host configuration is correct
|
|
215
|
+
|
|
216
|
+
3. **Empty Results**
|
|
217
|
+
- Verify the collection name is correct
|
|
218
|
+
- Try broadening your search query
|
|
219
|
+
|
|
220
|
+
### Logging
|
|
221
|
+
|
|
222
|
+
The server uses Python's logging module with INFO level by default. You can see detailed logs in the console when running the server.
|
|
223
|
+
|
|
224
|
+
## Contributing
|
|
225
|
+
|
|
226
|
+
Contributions to improve the Viking Knowledge Base MCP Server are welcome. Please follow these steps:
|
|
227
|
+
|
|
228
|
+
1. Fork the repository
|
|
229
|
+
2. Create a feature branch
|
|
230
|
+
3. Make your changes
|
|
231
|
+
4. Submit a pull request
|
|
232
|
+
|
|
233
|
+
Please ensure your code follows the project's coding standards and includes appropriate tests.
|
|
234
|
+
|
|
235
|
+
## License
|
|
236
|
+
|
|
237
|
+
volcengine/mcp-server is licensed under the [MIT License](https://github.com/volcengine/mcp-server/blob/main/LICENSE).
|
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
# Viking Knowledge Base MCP Server
|
|
2
|
+
|
|
3
|
+
## 产品描述
|
|
4
|
+
|
|
5
|
+
Viking Knowledge Base MCP Server 是一个模型上下文协议(Model Context Protocol)服务器,为MCP客户端(如Claude Desktop)提供与火山引擎知识库KnowledgeBase服务交互的能力。知识库MCP Server支持获取用户账号下的所有知识库列表,并在指定的知识库中检索结果。同时支持您以url上传的方式将文档上传到您的知识库,也支持查看文档和知识库的状态信息。
|
|
6
|
+
|
|
7
|
+
## 分类
|
|
8
|
+
其他
|
|
9
|
+
|
|
10
|
+
## 功能
|
|
11
|
+
|
|
12
|
+
- 获取用户账号下的所有知识库列表
|
|
13
|
+
- 在指定的知识库中检索结果
|
|
14
|
+
- 以url上传的方式将文档上传到您的知识库
|
|
15
|
+
- 查看文档的处理状态
|
|
16
|
+
- 查看知识库的状态
|
|
17
|
+
|
|
18
|
+
## 使用指南
|
|
19
|
+
|
|
20
|
+
### 前置准备
|
|
21
|
+
- Python 3.10+
|
|
22
|
+
- UV
|
|
23
|
+
- 知识库 API Key 或火山引擎 AK/SK
|
|
24
|
+
|
|
25
|
+
### 安装
|
|
26
|
+
克隆仓库:
|
|
27
|
+
```bash
|
|
28
|
+
git clone git@github.com:volcengine/mcp-server.git
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
### 使用方法
|
|
32
|
+
启动服务器:
|
|
33
|
+
|
|
34
|
+
#### UV
|
|
35
|
+
```bash
|
|
36
|
+
cd mcp-server/server/mcp_server_knowledgebase
|
|
37
|
+
uv run mcp-server-knowledgebase
|
|
38
|
+
|
|
39
|
+
# 使用无状态 Streamable HTTP 模式启动(默认为 stdio)
|
|
40
|
+
uv run mcp-server-knowledgebase -t streamable-http
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Streamable HTTP 默认地址为 `http://127.0.0.1:8000/mcp`。在可信网关后部署时,
|
|
44
|
+
可设置 `MCP_SERVER_HOST=0.0.0.0`。
|
|
45
|
+
|
|
46
|
+
Server 使用 MCP Python SDK 2.x,支持 `2026-07-28` 协议修订版及
|
|
47
|
+
`server/discover` 无状态协商,同时由 SDK 自动兼容旧版握手客户端。
|
|
48
|
+
旧 HTTP+SSE 已被新协议弃用,因此本 Server 不再提供 SSE 启动模式。
|
|
49
|
+
|
|
50
|
+
Streamable HTTP 本身不会把知识库 API Key 或火山引擎 AK/SK 转换成 MCP 调用方认证。
|
|
51
|
+
远程部署必须放在认证网关之后或接入兼容 MCP 的 OAuth,且不得向调用方暴露服务凭证。
|
|
52
|
+
|
|
53
|
+
使用客户端与服务器交互:
|
|
54
|
+
```
|
|
55
|
+
Trae | Cursor | Claude Desktop | Cline | ...
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## 配置
|
|
59
|
+
|
|
60
|
+
### 环境变量
|
|
61
|
+
|
|
62
|
+
鉴权至少需要配置一种方式:配置 `VIKING_API_KEY`,或同时配置
|
|
63
|
+
`VOLCENGINE_ACCESS_KEY` 和 `VOLCENGINE_SECRET_KEY`。API Key 模式会通过
|
|
64
|
+
`Authorization: Bearer <VIKING_API_KEY>` 请求头鉴权;AK/SK 模式继续使用
|
|
65
|
+
SignerV4。两种方式可以同时配置,此时 `VIKING_API_KEY` 优先,AK/SK 会被
|
|
66
|
+
忽略。未配置 API Key 时,AK 和 SK 必须同时提供;没有可用鉴权方式时服务将
|
|
67
|
+
启动失败。
|
|
68
|
+
|
|
69
|
+
以下环境变量可用于配置MCP服务器:
|
|
70
|
+
|
|
71
|
+
| 环境变量 | 描述 | 默认值 |
|
|
72
|
+
|--------------------------|-----------------|-------|
|
|
73
|
+
| `VIKING_API_KEY` | 知识库 API Key(配置时优先使用) | - |
|
|
74
|
+
| `VOLCENGINE_ACCESS_KEY` | 火山引擎账号ACCESSKEY | - |
|
|
75
|
+
| `VOLCENGINE_SECRET_KEY` | 火山引擎账号SECRETKEY | - |
|
|
76
|
+
| `KNOWLEDGE_BASE_PROJECT` | 知识库所属项目 | `default` |
|
|
77
|
+
| `KNOWLEDGE_BASE_REGION` | 知识库区域 | cn-north-1 |
|
|
78
|
+
| `MCP_SERVER_HOST` | Streamable HTTP 监听地址 | `127.0.0.1` |
|
|
79
|
+
| `MCP_SERVER_PORT` | Streamable HTTP 端口(兼容 `PORT`) | `8000` |
|
|
80
|
+
| `STREAMABLE_HTTP_PATH` | Streamable HTTP 路径 | `/mcp` |
|
|
81
|
+
| `KNOWLEDGE_BASE_TIMEOUT` | 上游请求超时(秒) | `30` |
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
## 可用工具
|
|
85
|
+
|
|
86
|
+
Knowledge Base MCP Server 提供以下功能
|
|
87
|
+
|
|
88
|
+
- `add_doc`: [上传文档(目前仅支持url)](https://www.volcengine.com/docs/84313/1254624)
|
|
89
|
+
- `get_doc`: [获取指定文档的状态](https://www.volcengine.com/docs/84313/1254615)
|
|
90
|
+
- `get_collection`: [获取知识库的详细信息](https://www.volcengine.com/docs/84313/1254602)
|
|
91
|
+
- `list_colletions`: [获取指定账户和Project下的知识库列表](https://www.volcengine.com/docs/84313/1254596)
|
|
92
|
+
- `search_knowledge`: [在指定知识库中进行搜索](https://www.volcengine.com/docs/84313/1350012)
|
|
93
|
+
|
|
94
|
+
#### add_doc
|
|
95
|
+
|
|
96
|
+
```python
|
|
97
|
+
add_doc(
|
|
98
|
+
collection_name="collection_name",
|
|
99
|
+
add_type="url",
|
|
100
|
+
doc_id="mcp_server_auto_gen_doc_id_xxxxxxx",
|
|
101
|
+
doc_name="doc_xxxx",
|
|
102
|
+
doc_type="pdf",
|
|
103
|
+
url="http://xxxxx.pdf"
|
|
104
|
+
)
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Parameters:
|
|
108
|
+
- `collection_name` (必须): 要上传文档的知识库名称
|
|
109
|
+
- `add_type` (必须): 上传文档的添加类型, mcp server目前仅支持url
|
|
110
|
+
- `doc_id` (必须): url上传方式需要指定doc_id
|
|
111
|
+
- `doc_name` (必须): url 上传方式需要指定doc_name.
|
|
112
|
+
- `doc_type` (必须): 要添加的文档的类型。对于结构化文档,支持 xlsx、csv 和 jsonl;对于非结构化文档,我们支持 txt、doc、docx、pdf、markdown、faq.xlsx 和 pptx
|
|
113
|
+
- `url` (必须): 待添加文档的 URL
|
|
114
|
+
|
|
115
|
+
#### get_doc
|
|
116
|
+
|
|
117
|
+
```python
|
|
118
|
+
get_doc(
|
|
119
|
+
collection_name="collection_name",
|
|
120
|
+
doc_id="mcp_server_auto_gen_doc_id_xxxxxxx",
|
|
121
|
+
)
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Parameters:
|
|
125
|
+
- `collection_name` (必须): 要获取信息的文档所属的知识库
|
|
126
|
+
- `doc_id` (必须): 要获取信息的文档ID
|
|
127
|
+
|
|
128
|
+
#### get_collection
|
|
129
|
+
|
|
130
|
+
```python
|
|
131
|
+
get_collection(
|
|
132
|
+
collection_name="collection_name",
|
|
133
|
+
)
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Parameters:
|
|
137
|
+
- `collection_name` (必须): 要获取信息的知识库名称
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
#### list_collections
|
|
141
|
+
|
|
142
|
+
```python
|
|
143
|
+
list_collections()
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
#### search_knowledge
|
|
147
|
+
|
|
148
|
+
```python
|
|
149
|
+
search_knowledge(
|
|
150
|
+
query="How to reset my password?",
|
|
151
|
+
limit=3,
|
|
152
|
+
collection_name="collection_name"
|
|
153
|
+
)
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Parameters:
|
|
157
|
+
- `query` (必须): 搜索查询字符串
|
|
158
|
+
- `limit` (可选): 返回的最大结果数,范围 1–100(默认值:3)
|
|
159
|
+
- `collection_name` (必须): 要搜索的知识库名称
|
|
160
|
+
|
|
161
|
+
每条结果包含分块的 `id`、`content`,以及来源文档的 `doc_id` 和
|
|
162
|
+
`doc_name`;Viking 未提供文档元数据时,这两个字段为 `null`。非空的
|
|
163
|
+
`doc_id` 可以直接传给 `get_doc`。
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
### uvx 启动
|
|
167
|
+
```json
|
|
168
|
+
{
|
|
169
|
+
"mcpServers": {
|
|
170
|
+
"knowledgebase": {
|
|
171
|
+
"command": "uvx",
|
|
172
|
+
"args": [
|
|
173
|
+
"--from",
|
|
174
|
+
"mcp-server-knowledgebase>=0.2.0",
|
|
175
|
+
"mcp-server-knowledgebase"
|
|
176
|
+
],
|
|
177
|
+
"env": {
|
|
178
|
+
"VIKING_API_KEY": "your-viking-api-key",
|
|
179
|
+
"KNOWLEDGE_BASE_PROJECT": "your-project-name",
|
|
180
|
+
"KNOWLEDGE_BASE_REGION": "your-region"
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
也可以额外或改为同时配置 `VOLCENGINE_ACCESS_KEY` 和
|
|
188
|
+
`VOLCENGINE_SECRET_KEY`。三个变量均配置时,优先使用 `VIKING_API_KEY`。
|
|
189
|
+
|
|
190
|
+
## 证书
|
|
191
|
+
volcengine/mcp-server is licensed under the [MIT License](https://github.com/volcengine/mcp-server/blob/main/LICENSE).
|