mcp-server-knowledgebase 0.2.0__py3-none-any.whl

mcp_server_knowledgebase/__init__.py

@@ -0,0 +1 @@
+# Package initialization

mcp_server_knowledgebase/common/auth.py

@@ -0,0 +1,53 @@
+import json
+
+from volcengine.auth.SignerV4 import SignerV4
+from volcengine.base.Request import Request
+from volcengine.Credentials import Credentials
+from mcp_server_knowledgebase.config import config
+
+
+def prepare_request(
+    method, path, ak=None, sk=None, params=None, data=None, doseq=0, *, api_key=None
+):
+    ak = ak.strip() if isinstance(ak, str) else ak
+    sk = sk.strip() if isinstance(sk, str) else sk
+    api_key = api_key.strip() if isinstance(api_key, str) else api_key
+
+    if not api_key:
+        if bool(ak) != bool(sk):
+            raise ValueError("AK and SK must be configured together")
+        if not ak or not sk:
+            raise ValueError("Configure an authentication method: VIKING_API_KEY or AK/SK")
+
+    if params:
+        for key in params:
+            if (
+                type(params[key]) == int
+                or type(params[key]) == float
+                or type(params[key]) == bool
+            ):
+                params[key] = str(params[key])
+            elif type(params[key]) == list:
+                if not doseq:
+                    params[key] = ",".join(params[key])
+    r = Request()
+    r.set_shema("https")
+    r.set_method(method)
+    r.set_connection_timeout(10)
+    r.set_socket_timeout(10)
+    mheaders = {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+    }
+    if api_key:
+        mheaders["Authorization"] = f"Bearer {api_key}"
+    r.set_headers(mheaders)
+    if params:
+        r.set_query(params)
+    r.set_path(path)
+    if data is not None:
+        r.set_body(json.dumps(data))
+    if not api_key:
+        credentials = Credentials(ak, sk, "air", config.region)
+        SignerV4.sign(r, credentials)
+    return r

mcp_server_knowledgebase/config.py

@@ -0,0 +1,57 @@
+import logging
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class KnowledgeBaseConfig:
+    """Configuration for Viking Knowledge Base MCP Server."""
+
+    ak: Optional[str] = None
+    sk: Optional[str] = None
+    project: Optional[str] = None
+    region: str = "cn-north-1"
+    api_key: Optional[str] = None
+
+
+def _credential_from_env(name: str) -> Optional[str]:
+    value = os.environ.get(name)
+    if value is None:
+        return None
+    return value.strip() or None
+
+
+def load_config() -> KnowledgeBaseConfig:
+    """Load configuration from environment variables."""
+    ak = _credential_from_env("VOLCENGINE_ACCESS_KEY")
+    sk = _credential_from_env("VOLCENGINE_SECRET_KEY")
+    api_key = _credential_from_env("VIKING_API_KEY")
+
+    if not api_key and bool(ak) != bool(sk):
+        error_msg = (
+            "VOLCENGINE_ACCESS_KEY and VOLCENGINE_SECRET_KEY must be configured together"
+        )
+        logger.error(error_msg)
+        raise ValueError(error_msg)
+
+    if not api_key and not (ak and sk):
+        error_msg = (
+            "Configure an authentication method: VIKING_API_KEY or "
+            "VOLCENGINE_ACCESS_KEY with VOLCENGINE_SECRET_KEY"
+        )
+        logger.error(error_msg)
+        raise ValueError(error_msg)
+
+    return KnowledgeBaseConfig(
+        ak=ak,
+        sk=sk,
+        api_key=api_key,
+        project=os.environ.get("KNOWLEDGE_BASE_PROJECT", "default"),
+        region=os.environ.get("KNOWLEDGE_BASE_REGION", "cn-north-1"),
+    )
+
+
+config = load_config()

mcp_server_knowledgebase/models.py

@@ -0,0 +1,66 @@
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class DocFilter(BaseModel):
+    """Filter applied to Viking Knowledge Base search results."""
+
+    op: Literal["must", "must_not"]
+    field: str = Field(min_length=1)
+    conds: list[Any] = Field(min_length=1)
+
+
+class AddDocumentResult(BaseModel):
+    collection_name: str
+    doc_id: str
+
+
+class DocumentStatus(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    process_status: Optional[int] = None
+    failed_code: Optional[str] = None
+
+
+class DocumentInfo(BaseModel):
+    """Known document fields; extra upstream fields are preserved."""
+
+    model_config = ConfigDict(extra="allow")
+
+    collection_name: Optional[str] = None
+    doc_id: Optional[str] = None
+    doc_name: Optional[str] = None
+    doc_type: Optional[str] = None
+    url: Optional[str] = None
+    add_type: Optional[str] = None
+    create_time: Optional[int] = None
+    update_time: Optional[int] = None
+    point_num: Optional[int] = None
+    status: Optional[DocumentStatus] = None
+
+
+class CollectionInfoResult(BaseModel):
+    collection_name: str
+    description: str
+    status: int
+
+
+class CollectionSummary(BaseModel):
+    collection_name: str
+    description: str
+
+
+class ListCollectionsResult(BaseModel):
+    collection_list: list[CollectionSummary]
+
+
+class SearchChunk(BaseModel):
+    id: str
+    content: str
+    doc_id: Optional[str] = None
+    doc_name: Optional[str] = None
+
+
+class SearchKnowledgeResult(BaseModel):
+    result_list: list[SearchChunk]

mcp_server_knowledgebase/server.py

@@ -0,0 +1,421 @@
+import argparse
+import logging
+import os
+from typing import Annotated, Any, Dict, Literal, Optional
+
+import aiohttp
+from mcp.server import MCPServer
+from mcp.server.caching import CacheHint
+from mcp.server.mcpserver.exceptions import ToolError
+from mcp.types import ToolAnnotations
+from pydantic import Field
+
+from mcp_server_knowledgebase.common.auth import prepare_request
+from mcp_server_knowledgebase.config import config
+from mcp_server_knowledgebase.models import (
+    AddDocumentResult,
+    CollectionInfoResult,
+    CollectionSummary,
+    DocFilter,
+    DocumentInfo,
+    ListCollectionsResult,
+    SearchChunk,
+    SearchKnowledgeResult,
+)
+
+logger = logging.getLogger(__name__)
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+
+# knowledge base domain
+g_knowledge_base_domain = "api-knowledgebase.mlp.cn-beijing.volces.com"
+
+# paths
+search_knowledge_path = "/api/knowledge/collection/search_knowledge"
+list_collections_path = "/api/knowledge/collection/list"
+get_collections_path = "/api/knowledge/collection/info"
+doc_add_path = "/api/knowledge/doc/add"
+doc_info_path = "/api/knowledge/doc/info"
+
+# Create MCP server
+mcp = MCPServer(
+    "Knowledgebase MCP Server",
+    version="0.2.0",
+    cache_hints={"tools/list": CacheHint(ttl_ms=300_000, scope="public")},
+)
+
+
+def _transport_options(transport: str) -> Dict[str, Any]:
+    """Build transport-specific options accepted by MCP SDK v2."""
+    if transport == "stdio":
+        return {}
+    if transport != "streamable-http":
+        raise ValueError(f"Unsupported transport: {transport}")
+    return {
+        "host": os.getenv("MCP_SERVER_HOST", "127.0.0.1"),
+        "port": int(os.getenv("MCP_SERVER_PORT") or os.getenv("PORT", "8000")),
+        "streamable_http_path": os.getenv("STREAMABLE_HTTP_PATH", "/mcp"),
+        "stateless_http": True,
+        "json_response": True,
+    }
+
+
+async def _request_knowledgebase(path: str, data: Dict[str, Any]) -> Dict[str, Any]:
+    """Send one signed request without blocking the MCP event loop."""
+    request = prepare_request(
+        method="POST",
+        path=path,
+        ak=config.ak,
+        sk=config.sk,
+        api_key=config.api_key,
+        data=data,
+    )
+    timeout = aiohttp.ClientTimeout(total=float(os.getenv("KNOWLEDGE_BASE_TIMEOUT", "30")))
+    async with aiohttp.ClientSession(timeout=timeout) as session:
+        async with session.request(
+            method=request.method,
+            url=f"https://{g_knowledge_base_domain}{request.path}",
+            headers=request.headers,
+            data=request.body,
+        ) as response:
+            response.raise_for_status()
+            return await response.json()
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        readOnlyHint=False,
+        destructiveHint=False,
+        idempotentHint=False,
+        openWorldHint=True,
+    )
+)
+async def add_doc(
+    collection_name: Annotated[str, Field(min_length=1)],
+    add_type: Literal["url"],
+    doc_id: Annotated[
+        str,
+        Field(min_length=1, max_length=128, pattern=r"^[A-Za-z][A-Za-z0-9_]*$"),
+    ],
+    doc_name: Annotated[str, Field(min_length=1, max_length=256)],
+    doc_type: Literal[
+        "xlsx",
+        "csv",
+        "jsonl",
+        "txt",
+        "doc",
+        "docx",
+        "pdf",
+        "markdown",
+        "faq.xlsx",
+        "pptx",
+    ],
+    url: Annotated[str, Field(min_length=1)],
+) -> AddDocumentResult:
+    """
+    Add a document to a collection in your project.
+    This tool allows you to add a document to a collection in your project by collection_name.
+    Args:
+         collection_name: the name of the knowledge base collection to add document to.
+         add_type: the type of the document to add. so far only support "url" now. so you must assign this parameter to "url".
+         doc_id: 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.
+         doc_name: the name of the document to add. you can1 generate a unique doc_name based on user given url and timestamp. the length of doc_name must between 1 and 256. you can use a
+                format like "mcp_server_auto_gen_doc_name_xxxxxxx.
+         doc_type: 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.
+         url: the url of the document to add. user should give a valid url, we will add the doc to the collection.
+
+    Returns:
+        collection_name: the name of the knowledge base collection.
+        doc_id: the doc_id of document user added to collection.
+
+    """
+    try:
+        if not collection_name:
+            raise ValueError("Collection name cannot be empty.")
+
+        request_params = {
+            "collection_name": collection_name,
+            "project": config.project,
+            "add_type": add_type,
+            "doc_id": doc_id,
+            "doc_name": doc_name,
+            "doc_type": doc_type,
+            "url": url,
+        }
+
+        result = await _request_knowledgebase(doc_add_path, request_params)
+        if result['code'] != 0:
+            logger.error(f"Error in add_doc: {result['message']}")
+            raise ToolError(result['message'])
+
+        doc_add_data = result['data']
+        if not doc_add_data:
+            raise ValueError(f"doc {doc_id} has no data.")
+
+        return AddDocumentResult(collection_name=collection_name, doc_id=doc_id)
+
+    except ToolError:
+        raise
+    except Exception as e:
+        logger.error(f"Error in add_doc: {str(e)}")
+        raise ToolError(str(e)) from e
+
+
+@mcp.tool(annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True))
+async def get_doc(
+    collection_name: str,
+    doc_id: str,
+) -> DocumentInfo:
+    """
+    Get information about a document from your collection.
+    This tool allows you to get information about a document from your project by collection_name and doc_id.
+    Args:
+         collection_name: the name of the knowledge base collection to get document from.
+         doc_id: the doc_id of document user want to get information.
+    Returns:
+        collection_name: the name of the knowledge base collection.
+        doc_id: the doc_id of document user added to collection.
+        doc_name: the name of the document.
+        doc_type: the type of the document.
+        url: the url of the document.
+        add_type: the type how to add document.
+        create_time: the time when document added to collection.
+        update_time: the time when document updated.
+        point_num: The number of points extracted from the document.
+        status: the status of the document. the status struct has two fields:
+            - process_status: The processing status of the document.
+                                0 means the processing is completed,
+                                1 means the processing failed,
+                                2 or 3 means it is in queue,
+                                5 means it is being deleted,
+                                and 6 means it is processing.
+            - failed_code: the status message of the document.
+    """
+
+    try:
+        if not collection_name:
+            raise ValueError("Collection name cannot be empty.")
+
+        request_params = {
+            "collection_name": collection_name,
+            "project": config.project,
+            "doc_id": doc_id,
+        }
+
+        result = await _request_knowledgebase(doc_info_path, request_params)
+        if result['code'] != 0:
+            logger.error(f"Error in get_doc: {result['message']}")
+            raise ToolError(result['message'])
+
+        doc_info_data = result['data']
+        if not doc_info_data:
+            raise ValueError(f"doc {doc_id} not found.")
+
+        return DocumentInfo.model_validate(doc_info_data)
+
+    except ToolError:
+        raise
+    except Exception as e:
+        logger.error(f"Error in get_doc: {str(e)}")
+        raise ToolError(str(e)) from e
+
+
+@mcp.tool(annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True))
+async def get_collection(
+    collection_name: str,
+) -> CollectionInfoResult:
+    """
+    Get information about a collection from your project.
+    This tool allows you to get information about a collection from your project by collection_name.
+    Args:
+         collection_name: the name of the knowledge base collection to get info for.
+
+    Returns:
+        collection_name: the name of the knowledge base collection.
+        description: the description of the knowledge base collection.
+        status: the status of the knowledge base collection.
+        status：
+            -1: To be built
+            0: Building
+            1: Build completed
+            2: Build failed
+            3: Changing
+
+    """
+
+    try:
+        if not collection_name:
+            raise ValueError("Collection name cannot be empty.")
+
+        request_params = {
+            "name": collection_name,
+            "project": config.project,
+        }
+
+        result = await _request_knowledgebase(get_collections_path, request_params)
+        if result['code'] != 0:
+            logger.error(f"Error in search_knowledge: {result['message']}")
+            raise ToolError(result['message'])
+
+        collection_info = result['data']
+        if not collection_info:
+            raise ValueError(f"Collection {collection_name} not found.")
+
+        return CollectionInfoResult(
+            collection_name=collection_info["collection_name"],
+            description=collection_info["description"],
+            status=collection_info["pipeline_list"][0]["index_list"][0]["status"],
+        )
+
+    except ToolError:
+        raise
+    except Exception as e:
+        logger.error(f"Error in get_collection: {str(e)}")
+        raise ToolError(str(e)) from e
+
+
+@mcp.tool(annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True))
+async def list_collections() -> ListCollectionsResult:
+    """
+    List all collections of the globally configured project from the Viking Knowledgebase service.
+    This tool allows you to list all collections in the Viking Knowledgebase service.
+
+    Returns:
+        A list of collections in the project.
+        collection_name: the name of the knowledge base collection.
+        description: the description of the knowledge base collection.
+
+    """
+
+    try:
+        request_params = {
+            "project": config.project,
+        }
+
+        result = await _request_knowledgebase(list_collections_path, request_params)
+        if result['code'] != 0:
+            logger.error(f"Error in list_collections: {result['message']}")
+            raise ToolError(result['message'])
+
+        collections = result['data']['collection_list']
+
+        collection_list = []
+
+        for collection in collections:
+            collection_list.append(
+                CollectionSummary(
+                    collection_name=collection["collection_name"],
+                    description=collection["description"],
+                )
+            )
+
+        return ListCollectionsResult(collection_list=collection_list)
+
+    except ToolError:
+        raise
+    except Exception as e:
+        logger.error(f"Error in list_collections: {str(e)}")
+        raise ToolError(str(e)) from e
+
+
+@mcp.tool(annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True))
+async def search_knowledge(
+    query: str,
+    collection_name: str,
+    limit: Annotated[int, Field(ge=1, le=100)] = 3,
+    doc_filter: Optional[DocFilter] = None,
+) -> SearchKnowledgeResult:
+    """Search knowledge from the Viking Knowledgebase service And return Top limit related chunks of your query.
+    This tool allows you to search knowledge in provided collection based on the given query.
+
+    Args:
+        query: the search query string.
+        limit: the maximum number of results to return (default: 3).
+        collection_name: the name of the knowledge base collection to search for.
+        doc_filter: the filter is used to filter search results(default: None), which is structured as a JSON object with
+        the following key components:
+        - '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).
+        - 'field':  (string, required) indicates the specific document field to apply the filter on (e.g., "doc_id").
+        - 'conds': (array, required) contains the concrete values used for filtering. The data type
+            of elements in the array depends on the field.
+
+    Returns:
+        A list of search results.
+        id: the id of the knowledge base chunk.
+        content: the content of the knowledge base chunk.
+        doc_id: the id of the document containing the chunk, when available.
+        doc_name: the name of the document containing the chunk, when available.
+    """
+
+    try:
+        if not collection_name:
+            raise ValueError("Collection name cannot be empty.")
+
+        request_params = {
+            "query": query,
+            "limit": limit,
+            "name": collection_name,
+            "project": config.project,
+        }
+
+        if doc_filter:
+            request_params['query_param'] = {
+                "doc_filter": doc_filter.model_dump(mode="json"),
+            }
+
+        result = await _request_knowledgebase(search_knowledge_path, request_params)
+        if result['code'] != 0:
+            logger.error(f"Error in search_knowledge: {result['message']}")
+            raise ToolError(result['message'])
+
+        chunks = result['data'].get('result_list', [])
+
+        search_result = []
+
+        for chunk in chunks:
+            raw_doc_info = chunk.get("doc_info")
+            doc_info = raw_doc_info if isinstance(raw_doc_info, dict) else {}
+            search_result.append(
+                SearchChunk(
+                    id=chunk["id"],
+                    content=chunk["content"],
+                    doc_id=doc_info.get("doc_id"),
+                    doc_name=doc_info.get("doc_name"),
+                )
+            )
+
+        return SearchKnowledgeResult(result_list=search_result)
+    except ToolError:
+        raise
+    except Exception as e:
+        logger.error(f"Error in search_knowledge: {str(e)}")
+        raise ToolError(str(e)) from e
+
+
+def main():
+    """Main entry point for the Knowledgebase MCP server."""
+    parser = argparse.ArgumentParser(description='Run the Viking Knowledgebase MCP Server')
+    parser.add_argument(
+        "--transport",
+        "-t",
+        choices=["stdio", "streamable-http"],
+        default="stdio",
+        help="Transport protocol to use (stdio or streamable-http)",
+    )
+    args = parser.parse_args()
+    logger.info(f"Starting Knowledgebase MCP Server with {args.transport} transport")
+
+    try:
+        mcp.run(transport=args.transport, **_transport_options(args.transport))
+    except Exception as e:
+        logger.error(f"Error starting Knowledgebase MCP Server: {str(e)}")
+        raise
+
+
+if __name__ == "__main__":
+    main()

mcp_server_knowledgebase-0.2.0.dist-info/METADATA

@@ -0,0 +1,248 @@
+Metadata-Version: 2.5
+Name: mcp-server-knowledgebase
+Version: 0.2.0
+Summary: MCP server for Viking Knowledge Base Service
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.11.14
+Requires-Dist: mcp[cli]<3,>=2.1.1
+Requires-Dist: volcengine>=1.0.171
+Description-Content-Type: text/markdown
+
+# Viking Knowledge Base MCP Server
+
+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,
+allowing you to add doc to your collections and get doc processing info by doc_id.
+
+## Features
+
+- Search knowledge based on queries with customizable parameters
+
+## Setup
+
+### Prerequisites
+
+- Python 3.10 or higher
+- A Viking Knowledge Base API key or VolcEngine AK/SK credentials
+
+### Installation
+
+1. Install the package:
+
+```bash
+pip install -e .
+```
+
+Or with uv (recommended):
+
+```bash
+uv pip install -e .
+```
+
+### Configuration
+
+The server requires at least one authentication method:
+
+- API key: set `VIKING_API_KEY`. Requests use
+  `Authorization: Bearer <VIKING_API_KEY>`.
+- AK/SK: set both `VOLCENGINE_ACCESS_KEY` and `VOLCENGINE_SECRET_KEY`.
+  Requests use VolcEngine SignerV4 authentication.
+
+When both methods are configured, `VIKING_API_KEY` takes precedence and AK/SK
+is ignored. When no API key is configured, AK and SK must be provided together.
+The server rejects configurations with no usable authentication method.
+
+Optional environment variables:
+- `KNOWLEDGE_BASE_PROJECT`: Viking Knowledge Base project name (default: `default`)
+- `KNOWLEDGE_BASE_REGION`: Viking Knowledge Base region (default: `cn-north-1`)
+- `MCP_SERVER_HOST`: Streamable HTTP bind host (default: `127.0.0.1`)
+- `MCP_SERVER_PORT`: Streamable HTTP port; falls back to `PORT` (default: `8000`)
+- `STREAMABLE_HTTP_PATH`: Streamable HTTP endpoint path (default: `/mcp`)
+- `KNOWLEDGE_BASE_TIMEOUT`: Upstream request timeout in seconds (default: `30`)
+
+## Usage
+
+### Running the Server
+
+The server supports stdio for local integrations and stateless Streamable HTTP
+for remote deployments:
+
+```bash
+python -m mcp_server_knowledgebase.server --transport stdio
+```
+
+Or:
+
+```bash
+python -m mcp_server_knowledgebase.server --transport streamable-http
+```
+
+The Streamable HTTP endpoint is `http://127.0.0.1:8000/mcp` by default.
+Set `MCP_SERVER_HOST=0.0.0.0` when running behind a trusted gateway.
+
+### MCP protocol compatibility
+
+This server uses MCP Python SDK 2.x and speaks protocol revision `2026-07-28`.
+Modern clients use the stateless per-request protocol and `server/discover`;
+the same process also supports older handshake-based clients automatically.
+Legacy HTTP+SSE is intentionally not exposed because it is deprecated by the
+`2026-07-28` specification.
+
+The HTTP endpoint does not turn the configured API key or VolcEngine AK/SK into
+client authentication. Protect remote deployments with an authentication
+gateway or MCP-compatible OAuth, and never expose the service credentials to
+callers.
+
+### Available Tools
+
+#### add_doc
+
+Add a document to a collection in your project.
+
+```python
+add_doc(
+    collection_name="collection_name",
+    add_type="url",
+    doc_id="mcp_server_auto_gen_doc_id_xxxxxxx",
+    doc_name="doc_xxxx",
+    doc_type="pdf",
+    url="http://xxxxx.pdf"
+)
+```
+
+Parameters:
+- `collection_name` (required): the name of the collection you want to add document .
+- `add_type` (required): the type of the document to add. so far only support "url" now. 
+- `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".
+- `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".
+- `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.
+- `url` (required): the url of the document to add. user should give a valid url, we will add the doc to the collection.
+
+#### get_doc
+
+Get information about document by collection_name and doc_id .
+
+```python
+get_doc(
+    collection_name="collection_name",
+    doc_id="mcp_server_auto_gen_doc_id_xxxxxxx",
+)
+```
+
+Parameters:
+- `collection_name` (required): the name of the collection you want to get information .
+- `doc_id` (required): the doc_id of document user want to get information .
+
+#### get_collection
+
+Get information about a viking knowledge base collection from your project .
+
+```python
+get_collection(
+    collection_name="collection_name",
+)
+```
+
+Parameters:
+- `collection_name` (required): the name of the collection you want to get information .
+
+
+#### list_collections
+
+List all knowledge base collections of the globally configured project .
+
+```python
+list_collections(
+)
+```
+
+
+#### search_knowledge
+
+Search for knowledge in the configured collection based on a query.
+
+```python
+search_knowledge(
+    query="How to reset my password?",
+    limit=3,
+    collection_name="collection_name",
+    doc_filter=None,
+)
+```
+
+Parameters:
+- `query` (required): The search query string
+- `limit` (optional): Maximum number of results to return, from 1 to 100 (default: 3)
+- `collection_name` (required): Knowledge Base collection name to search
+- `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:
+  - `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).
+  - `field` (string, required): indicates the specific document field to apply the filter on (e.g., "doc_id").
+  - `conds` (array, required):  contains the concrete values used for filtering. The data type of elements in the array depends on the field.
+
+Each result contains the chunk `id` and `content`, plus the source document's
+`doc_id` and `doc_name`. The metadata fields are `null` when Viking does not
+provide them. A non-null `doc_id` can be passed directly to `get_doc`.
+
+## MCP Integration
+
+To add this server to your MCP configuration, add the following to your MCP settings file:
+
+```json
+{
+  "mcpServers": {
+    "knowledgebase": {
+      "command": "uvx",
+        "args": [
+          "--from",
+          "mcp-server-knowledgebase>=0.2.0",
+          "mcp-server-knowledgebase"
+      ],
+      "env": {
+        "VIKING_API_KEY": "your-viking-api-key",
+        "KNOWLEDGE_BASE_PROJECT": "your-project-name",
+        "KNOWLEDGE_BASE_REGION": "your-region"
+      }
+    }
+  }
+}
+```
+
+You may alternatively or additionally configure both
+`VOLCENGINE_ACCESS_KEY` and `VOLCENGINE_SECRET_KEY`. If all three variables are
+set, `VIKING_API_KEY` takes precedence.
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Authentication Errors**
+   - Verify your API key or AK/SK credentials are correct
+   - Ensure at least one authentication method is configured
+   - Check that you have the necessary permissions for the collection
+
+2. **Connection Timeouts**
+   - Check your network connection to the VolcEngine API
+   - Verify the host configuration is correct
+
+3. **Empty Results**
+   - Verify the collection name is correct
+   - Try broadening your search query
+
+### Logging
+
+The server uses Python's logging module with INFO level by default. You can see detailed logs in the console when running the server.
+
+## Contributing
+
+Contributions to improve the Viking Knowledge Base MCP Server are welcome. Please follow these steps:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request
+
+Please ensure your code follows the project's coding standards and includes appropriate tests.
+
+## License
+
+volcengine/mcp-server is licensed under the [MIT License](https://github.com/volcengine/mcp-server/blob/main/LICENSE).

mcp_server_knowledgebase-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+mcp_server_knowledgebase/__init__.py,sha256=aUck0pBUWsafYyf6Ch2F7iYQaxLQrH198HQbXPDp8ms,25
+mcp_server_knowledgebase/config.py,sha256=jQdEtU3ho37T88w-IuFCaYK4OP9g_rLN7hiwpo-0S7M,1580
+mcp_server_knowledgebase/models.py,sha256=Gly__XmaYyU1bjzPqm9hU9wb4XXQ97iywSWxzAvT6Ns,1541
+mcp_server_knowledgebase/server.py,sha256=73D_84J8LebZK8BbnhYBatqYQSOfR2VXKyjjsRSJRME,15546
+mcp_server_knowledgebase/common/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mcp_server_knowledgebase/common/auth.py,sha256=SV2fVjtto321yKPYTCK56D_Q6MSqyuN8ey-Mee1PzNg,1710
+mcp_server_knowledgebase-0.2.0.dist-info/METADATA,sha256=sYuZbYuSIsuYji8QvhTtu3fhs_YXhr13UvB0xCVgRLU,8408
+mcp_server_knowledgebase-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+mcp_server_knowledgebase-0.2.0.dist-info/entry_points.txt,sha256=Ou4PBntYVXnKxPxzpNWCyVEPaJySuEIY24xogVOeGcw,82
+mcp_server_knowledgebase-0.2.0.dist-info/RECORD,,

mcp_server_knowledgebase-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mcp_server_knowledgebase-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-server-knowledgebase = mcp_server_knowledgebase.server:main