### Create and Start MaxKB Container After Upgrade

Source: https://github.com/1panel-dev/maxkb/wiki/1-安装部署

Create and start a new MaxKB container using the latest image. Ensure the data persistence volume (-v) matches the one from the previous installation to avoid data loss.

```bash
docker run -d --name=maxkb -p 8080:8080 -v ~/.maxkb:/var/lib/postgresql/data cr2.fit2cloud.com/1panel/maxkb

# 注意：确认数据持久化目录（-v后的目录）要跟【第 2 步】的目录保持一致，否则启动后数据为空。

```

--------------------------------

### Docker Quick Start for MaxKB

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Starts MaxKB with a persistent volume using Docker. Default credentials are provided for initial access.

```bash
# Start MaxKB with persistent volume
docker run -d \
  --name=maxkb \
  --restart=always \
  -p 8080:8080 \
  -v ~/.maxkb:/opt/maxkb \
  1panel/maxkb

# Default credentials
# URL:      http://your_server_ip:8080
# Username: admin
# Password: MaxKB@123..

```

--------------------------------

### Install Project Dependencies

Source: https://github.com/1panel-dev/maxkb/blob/v2/ui/README.md

Run this command to install all necessary project dependencies after cloning the repository.

```sh
npm install
```

--------------------------------

### Install MaxKB Offline

Source: https://github.com/1panel-dev/maxkb/wiki/1-安装部署

Navigate to the extracted directory and execute the install script to set up MaxKB offline. This is recommended for production environments.

```bash
# 进入安装包解压缩后目录  
cd maxkb-v1.2.0-offline

# 执行安装命令
bash install.sh

```

--------------------------------

### Run Development Server

Source: https://github.com/1panel-dev/maxkb/blob/v2/ui/README.md

Starts the Vite development server with hot-reloading enabled for rapid development.

```sh
npm run dev
```

--------------------------------

### Run MaxKB with Docker

Source: https://github.com/1panel-dev/maxkb/blob/v2/README.md

Execute this script to start a MaxKB container. Access the web interface at http://your_server_ip:8080 with default credentials.

```bash
docker run -d --name=maxkb --restart=always -p 8080:8080 -v ~/.maxkb:/opt/maxkb 1panel/maxkb
```

--------------------------------

### MaxKB config.yml Reference

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Example configuration file for MaxKB, showing settings for database, Redis, and language. This file is typically located at /opt/maxkb/conf/config.yml.

```yaml
# /opt/maxkb/conf/config.yml
DB_NAME: maxkb
DB_HOST: 127.0.0.1
DB_PORT: 5432
DB_USER: root
DB_PASSWORD: Password123@postgres
DB_ENGINE: dj_db_conn_pool.backends.postgresql
DB_MAX_OVERFLOW: 80

REDIS_HOST: 127.0.0.1
REDIS_PORT: 6379
REDIS_PASSWORD: Password123@redis
REDIS_DB: 0
REDIS_MAX_CONNECTIONS: 100

LANGUAGE_CODE: zh-CN   # or en-US
SESSION_TIMEOUT: 28800  # seconds
DEBUG: false
LOG_LEVEL: INFO

```

--------------------------------

### Configure MCP Node (Inline Server)

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Sets up a node to call a remote MCP server tool. This example uses an inline server configuration.

```python
node_data = {
    "type": "mcp-node",
    "mcp_source": "inline",   # "inline" | "referencing"
    "mcp_servers": '{"jira": {"transport": "streamable_http", "url": "https://jira.example.com/mcp", "headers": {"Authorization": "Bearer TOKEN"}}}',
    "mcp_server": "jira",
    "mcp_tool": "create_issue",
    "tool_params": {
        "project": "SUPPORT",
        "summary": "{{global.question}}",
        "description": "{{ai_chat_node.answer}}"
    }
}
```

--------------------------------

### MaxKB Environment Variable Configuration

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Deploys MaxKB using environment variables for configuration, overriding the default config file. This example sets database and Redis connection details.

```bash
docker run -d \
  --name=maxkb \
  -p 8080:8080 \
  -e MAXKB_CONFIG_TYPE=ENV \
  -e MAXKB_DB_NAME=maxkb \
  -e MAXKB_DB_HOST=postgres \
  -e MAXKB_DB_PORT=5432 \
  -e MAXKB_DB_USER=maxkb \
  -e MAXKB_DB_PASSWORD=S3cr3tPass \
  -e MAXKB_REDIS_HOST=redis \
  -e MAXKB_REDIS_PORT=6379 \
  -e MAXKB_REDIS_PASSWORD=redispass \
  -e MAXKB_REDIS_DB=0 \
  -e MAXKB_LANGUAGE_CODE=en-US \
  1panel/maxkb

```

--------------------------------

### Add a Model to Workspace

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Registers a new model instance within a specific workspace, including its credentials. This example shows how to register an OpenAI GPT-4o model.

```bash
# Register an OpenAI GPT-4o model
curl -X POST "http://localhost:8080/api/workspace/default/model" \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GPT-4o",
    "provider": "openai_model_provider",
    "model_type": "LLM",
    "model_name": "gpt-4o",
    "credential": {
      "api_key": "sk-...",
      "api_base": "https://api.openai.com/v1"
    }
  }'
```

--------------------------------

### List Knowledge Bases (Paginated) API

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Retrieves a paginated list of knowledge bases within a workspace using GET to /api/workspace/{workspace_id}/knowledge/{current_page}/{page_size}. The response includes total count and records.

```bash
curl "http://localhost:8080/api/workspace/default/knowledge/1/10" \
  -H "Authorization: $TOKEN"

# Response
# {
#   "code": 200,
#   "data": {
#     "total": 3,
#     "records": [
#       { "id": "kb-uuid-001", "name": "Product Docs", "type": 0 },
#       ...
#     ]
#   }
# }

```

--------------------------------

### Get Application Statistics

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Retrieves usage statistics for an AI application, including total conversations, token usage, and top questions. This is useful for monitoring application performance and user engagement.

```bash
curl "http://localhost:8080/api/workspace/default/application/app-uuid-001/application_stats" \
  -H "Authorization: $TOKEN"
```

--------------------------------

### Initialize Admin UI Configuration

Source: https://github.com/1panel-dev/maxkb/blob/v2/ui/admin.html

Sets up the global MaxKB object with admin and chat prefixes. This is typically done during application initialization.

```javascript
window.MaxKB = { prefix: '/admin', chatPrefix: '/chat', }
```

--------------------------------

### Get Chat Records in a Session

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Retrieves all question-and-answer turns within a specific chat session.

```APIDOC
## GET /api/workspace/{workspace_id}/application/{application_id}/chat/{chat_id}/chat_record/{current_page}/{page_size}

### Description
Returns all Q&A turns within a specific chat session, paginated by current page and page size.

### Method
GET

### Endpoint
/api/workspace/{workspace_id}/application/{application_id}/chat/{chat_id}/chat_record/{current_page}/{page_size}

### Path Parameters
- **workspace_id** (string) - Required - The ID of the workspace.
- **application_id** (string) - Required - The ID of the application.
- **chat_id** (string) - Required - The ID of the chat session.
- **current_page** (integer) - Required - The current page number for pagination.
- **page_size** (integer) - Required - The number of items to display per page.

### Request Example
```bash
curl "http://localhost:8080/api/workspace/default/application/app-uuid-001/chat/$CHAT_ID/chat_record/1/50" \
  -H "Authorization: $TOKEN"
```
```

--------------------------------

### Get Captcha

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Retrieves a CAPTCHA image for human verification, typically used for chat widget authentication.

```APIDOC
## GET /chat/captcha

### Description
Returns a base64 CAPTCHA image when the application requires human verification.

### Method
GET

### Endpoint
`/chat/captcha`

### Query Parameters
- **username** (string) - Required - The username for which the CAPTCHA is generated.
- **accessToken** (string) - Required - A public access token.
```

--------------------------------

### Create a SIMPLE AI Application

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Use this endpoint to create a new AI application of type SIMPLE, which combines a single LLM with a knowledge base. Ensure you provide valid model and dataset IDs, along with detailed settings for knowledge retrieval and model behavior.

```bash
curl -X POST "http://localhost:8080/api/workspace/default/application" \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Bot",
    "desc": "Answers product questions using internal docs",
    "type": "SIMPLE",
    "model_id": "llm-model-uuid",
    "dataset_id_list": ["kb-uuid-001"],
    "prologue": "Hi! I am your support assistant. How can I help you today?",
    "dialogue_number": 5,
    "knowledge_setting": {
      "top_n": 5,
      "similarity": 0.6,
      "max_paragraph_char_number": 5000,
      "search_mode": "embedding",
      "no_references_setting": {
        "status": "ai_questioning",
        "value": "{question}"
      }
    },
    "model_setting": {
      "prompt": "You are a helpful customer support agent.\n\nContext:\n{data}\n\nUser: {question}",
      "no_references_prompt": "{question}",
      "reasoning_content_enable": false
    },
    "problem_optimization": true
  }'
```

--------------------------------

### Remove Running MaxKB Container

Source: https://github.com/1panel-dev/maxkb/wiki/1-安装部署

Forcefully remove the currently running MaxKB container before starting a new one during an upgrade process.

```bash
docker rm -f maxkb 

```

--------------------------------

### 在 Ollama 中创建模型

Source: https://github.com/1panel-dev/maxkb/wiki/如何使用Ollama离线部署LLM大语言模型

使用 `ollama create` 命令在 Ollama 中创建模型，需要指定模型名称和 Modelfile 文件路径。使用 `ollama list` 命令可以确认模型是否已成功创建。

```shell
ollama create qwen:0.5b -f Modelfile
```

```shell
ollama list
```

--------------------------------

### Create Web-Crawl Knowledge Base

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Create a knowledge base by providing URLs. MaxKB will crawl the specified sites, extract content, and split it into processable chunks. Configuration for crawling and content selection is done via the meta object.

```bash
curl -X POST "http://localhost:8080/api/workspace/default/knowledge/web" \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Site",
    "desc": "Scraped from docs.example.com",
    "embedding_model_id": "model-uuid-for-embedding",
    "meta": {
      "url": "https://docs.example.com",
      "selector_list": [".content"],
      "text_node_selector": "p,h1,h2",
      "sync_cron": "0 2 * * *"
    }
  }'
```

--------------------------------

### Get Chat Records in a Session

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Fetches all question-and-answer turns within a specific chat session. Supports pagination for large sessions.

```bash
curl "http://localhost:8080/api/workspace/default/application/app-uuid-001/chat/$CHAT_ID/chat_record/1/50" \
  -H "Authorization: $TOKEN"
```

--------------------------------

### Online Quick Deployment of MaxKB

Source: https://github.com/1panel-dev/maxkb/wiki/1-安装部署

Use this command to quickly deploy MaxKB online using Docker. Ensure the port is accessible and data is persisted to ~/.maxkb.

```bash
docker run -d --name=maxkb -p 8080:8080 -v ~/.maxkb:/var/lib/postgresql/data cr2.fit2cloud.com/1panel/maxkb

```

--------------------------------

### Get Captcha for Chat Widget Auth

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Retrieves a base64 encoded CAPTCHA image from the /chat/captcha endpoint. This is used for human verification when authenticating chat widgets.

```bash
curl "http://localhost:8080/chat/captcha?username=user1&accessToken=pub_token_abc"

```

--------------------------------

### Create a User (Admin)

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Use this endpoint to create a new user account. This operation is restricted to administrators.

```bash
curl -X POST "http://localhost:8080/api/user_manage" \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "jdoe",
    "password": "Str0ngPass!",
    "email": "jdoe@example.com",
    "nick_name": "John Doe",
    "phone": "+1-555-0100",
    "is_active": true
  }'
```

--------------------------------

### MCP List Available Tools

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Lists the tools available for use within an MCP session. This helps in understanding what actions can be performed by the model.

```bash
# 2. List available tools
curl -X POST "http://localhost:8080/chat/mcp" \
  -H "Authorization: Bearer application-abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'
```

--------------------------------

### Create a Web-Crawl Knowledge Base

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Creates a knowledge base from one or more URLs. MaxKB crawls the sites and automatically splits the content.

```APIDOC
## POST /api/workspace/{workspace_id}/knowledge/web

### Description
Creates a knowledge base from one or more URLs. MaxKB crawls the sites and automatically splits the content.

### Method
POST

### Endpoint
/api/workspace/{workspace_id}/knowledge/web

### Parameters
#### Path Parameters
- **workspace_id** (string) - Required - The ID of the workspace.

#### Request Body
- **name** (string) - Required - The name of the knowledge base.
- **desc** (string) - Optional - A description for the knowledge base.
- **embedding_model_id** (string) - Required - The ID of the embedding model to use.
- **meta** (object) - Required - Metadata for the web crawl.
  - **url** (string) - Required - The URL to crawl.
  - **selector_list** (array) - Optional - A list of CSS selectors to extract content from.
  - **text_node_selector** (string) - Optional - A CSS selector for text nodes.
  - **sync_cron** (string) - Optional - A cron string for periodic synchronization.

### Request Example
```bash
curl -X POST "http://localhost:8080/api/workspace/default/knowledge/web" \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Site",
    "desc": "Scraped from docs.example.com",
    "embedding_model_id": "model-uuid-for-embedding",
    "meta": {
      "url": "https://docs.example.com",
      "selector_list": [".content"],
      "text_node_selector": "p,h1,h2",
      "sync_cron": "0 2 * * *"
    }
  }'
```
```

--------------------------------

### Build for Production

Source: https://github.com/1panel-dev/maxkb/blob/v2/ui/README.md

Compiles and minifies the project for production deployment. This command also performs type-checking.

```sh
npm run build
```

--------------------------------

### 创建 Ollama Modelfile

Source: https://github.com/1panel-dev/maxkb/wiki/如何使用Ollama离线部署LLM大语言模型

创建一个 Modelfile 文件来定义模型的加载和配置。不同的模型可能需要不同的 Modelfile 内容，请参考 Ollama 官网的参数设置。

```shell
FROM ./qwen1_5-0_5b-chat-q5_k_m.gguf

TEMPLATE """{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>{{ end }}<|im_start|>user
{{ .Prompt }}<|im_end|>
<|im_start|>assistant
"""

PARAMETER stop "<|im_start|>"
PARAMETER stop "<|im_end|>"
```

--------------------------------

### Upload Document to Knowledge Base

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Use this endpoint to upload files for processing and vectorization. The backend supports various file types and automatically handles splitting and vectorization.

```bash
curl -X POST \
  "http://localhost:8080/api/workspace/default/knowledge/kb-uuid-001/document" \
  -H "Authorization: $TOKEN" \
  -F "file=@/path/to/manual.pdf" \
  -F 'meta={"directly_return_similarity": 0.9, "hit_handling_method": "optimization"}'
```

--------------------------------

### Export and Import Knowledge Base

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Download a knowledge base as a ZIP archive for backup or migration, or import a knowledge base from a ZIP file. These operations facilitate data management and transfer.

```bash
# Export as ZIP
curl -OJ \
  "http://localhost:8080/api/workspace/default/knowledge/kb-uuid-001/export_zip" \
  -H "Authorization: $TOKEN"
```

```bash
# Import from ZIP
curl -X POST \
  "http://localhost:8080/api/workspace/default/knowledge/import_knowledge" \
  -H "Authorization: $TOKEN" \
  -F "file=@knowledge_export.zip"
```

--------------------------------

### Export and Import AI Application Definitions

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Allows downloading the application definition (workflow, settings, prompts) as a JSON file for backup or cloning. The import functionality allows restoring or deploying this definition into another workspace.

```bash
# Export
curl -OJ \
  "http://localhost:8080/api/workspace/default/application/app-uuid-001/export" \
  -H "Authorization: $TOKEN"
```

```bash
# Import into another workspace
curl -X POST \
  "http://localhost:8080/api/workspace/staging/application/folder/default/import" \
  -H "Authorization: $TOKEN" \
  -F "file=@customer_support_bot.json"
```

--------------------------------

### Create Application

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Creates a new AI application. Applications can be of type SIMPLE (single LLM + knowledge base) or WORK_FLOW (full workflow graph).

```APIDOC
## POST /api/workspace/{workspace_id}/application

### Description
Creates a new AI application. Type can be `SIMPLE` (single LLM + knowledge base) or `WORK_FLOW` (full workflow graph).

### Method
POST

### Endpoint
`/api/workspace/{workspace_id}/application`

### Request Body
- **name** (string) - Required - The name of the application.
- **desc** (string) - Optional - A description for the application.
- **type** (string) - Required - The type of application, either `SIMPLE` or `WORK_FLOW`.
- **model_id** (string) - Required - The ID of the LLM model to use.
- **dataset_id_list** (array of strings) - Optional - A list of knowledge base dataset IDs.
- **prologue** (string) - Optional - The initial greeting message for the application.
- **dialogue_number** (integer) - Optional - The maximum number of dialogues to maintain.
- **knowledge_setting** (object) - Optional - Settings for knowledge base integration.
  - **top_n** (integer) - Optional - Number of top results to retrieve.
  - **similarity** (float) - Optional - Similarity threshold for search.
  - **max_paragraph_char_number** (integer) - Optional - Maximum characters per paragraph.
  - **search_mode** (string) - Optional - The search mode (e.g., `embedding`).
  - **no_references_setting** (object) - Optional - Settings for when no references are found.
    - **status** (string) - Required - Status of no references setting.
    - **value** (string) - Required - Value for the no references setting.
- **model_setting** (object) - Optional - Settings for the LLM model.
  - **prompt** (string) - Required - The prompt template for the model.
  - **no_references_prompt** (string) - Required - The prompt to use when no references are found.
  - **reasoning_content_enable** (boolean) - Optional - Whether to enable reasoning content.
- **problem_optimization** (boolean) - Optional - Whether to enable problem optimization.

### Request Example
```json
{
  "name": "Customer Support Bot",
  "desc": "Answers product questions using internal docs",
  "type": "SIMPLE",
  "model_id": "llm-model-uuid",
  "dataset_id_list": ["kb-uuid-001"],
  "prologue": "Hi! I am your support assistant. How can I help you today?",
  "dialogue_number": 5,
  "knowledge_setting": {
    "top_n": 5,
    "similarity": 0.6,
    "max_paragraph_char_number": 5000,
    "search_mode": "embedding",
    "no_references_setting": {
      "status": "ai_questioning",
      "value": "{question}"
    }
  },
  "model_setting": {
    "prompt": "You are a helpful customer support agent.\n\nContext:\n{data}\n\nUser: {question}",
    "no_references_prompt": "{question}",
    "reasoning_content_enable": false
  },
  "problem_optimization": true
}
```
```

--------------------------------

### MCP Initialize Session

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Initializes an MCP session. This is the first step in interacting with MaxKB applications via the Model Context Protocol.

```bash
# 1. Initialize MCP session
curl -X POST "http://localhost:8080/chat/mcp" \
  -H "Authorization: Bearer application-abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {}
  }'
```

--------------------------------

### Inspect MaxKB Container for Data Persistence Path

Source: https://github.com/1panel-dev/maxkb/wiki/1-安装部署

Inspect the running MaxKB container to retrieve the data persistence directory. This path is crucial for data consistency during upgrades.

```bash
docker inspect maxkb

```

--------------------------------

### Create Knowledge Base API

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Creates a new knowledge base of type BASE using POST to /api/workspace/{workspace_id}/knowledge/base. Requires an embedding model ID and returns details of the created base.

```bash
curl -X POST "http://localhost:8080/api/workspace/default/knowledge/base" \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Docs",
    "folder_id": "default",
    "desc": "Internal product documentation",
    "embedding_model_id": "model-uuid-for-embedding"
  }'

# Response
# {
#   "code": 200,
#   "data": {
#     "id": "kb-uuid-001",
#     "name": "Product Docs",
#     "type": 0,
#     "embedding_model_id": "model-uuid-for-embedding",
#     "create_time": "2025-06-01T10:00:00Z"
#   }
# }

```

--------------------------------

### OpenAI-Compatible Chat Completions

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Provides a drop-in OpenAI `chat/completions`-compatible endpoint. Any OpenAI SDK client can interact with a MaxKB application by setting the base URL to MaxKB.

```APIDOC
## POST /chat/{application_id}/chat/completions

### Description
This endpoint is compatible with OpenAI's `chat/completions` API, allowing seamless integration with existing OpenAI SDK clients. Point your SDK's base URL to your MaxKB instance to use it.

### Method
POST

### Endpoint
`/chat/{application_id}/chat/completions`

### Parameters
#### Path Parameters
- **application_id** (string) - Required - The ID of the MaxKB application.

#### Request Body
Refer to OpenAI's `chat/completions` API documentation for the request body structure. The `model` field is ignored as MaxKB uses the application's configured model.

### Request Example (Python SDK)
```python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/chat",
    api_key="application-abc123..."   # MaxKB application API key
)

response = client.chat.completions.create(
    model="default",   # model is ignored; MaxKB uses the application's configured model
    messages=[
        {"role": "user", "content": "Summarize the refund process"}
    ],
    stream=True
)

for chunk in response:
    print(chunk.choices[0].delta.content or "", end="", flush=True)
```
```

--------------------------------

### Configure MCP Node (Referencing Saved Tool)

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Configures a node to call a remote MCP server tool by referencing a pre-saved tool ID.

```python
node_data_ref = {
    "type": "mcp-node",
    "mcp_source": "referencing",
    "mcp_tool_id": "saved-mcp-tool-uuid",
    "mcp_server": "jira",
    "mcp_tool": "search_issues",
    "tool_params": {"jql": "project=SUPPORT AND status=Open"}
}
```

--------------------------------

### Configure Loop Node

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Sets up a node to iterate over a list, executing an inner workflow for each item. Define the list to iterate over and the variable name for each item.

```python
node_data = {
    "type": "loop-node",
    "iterate_over": ["search_knowledge_node", "paragraph_list"],
    "loop_variable_name": "current_paragraph",
    "max_iterations": 10,
    "child_nodes": [
        # array of inner workflow nodes executed per iteration
    ]
}
```

--------------------------------

### MCP Endpoint (JSON-RPC)

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Exposes MaxKB applications as MCP (Model Context Protocol) servers. Supports `initialize`, `tools/list`, and `tools/call` methods as defined by the MCP specification.

```APIDOC
## POST /chat/mcp

### Description
This endpoint implements the Model Context Protocol (MCP), allowing MaxKB applications to function as MCP servers. It supports the `initialize`, `tools/list`, and `tools/call` methods.

### Method
POST

### Endpoint
`/chat/mcp`

### Parameters
#### Request Body
The request body must be a JSON-RPC 2.0 object. Supported methods include:
- **initialize**: Initializes an MCP session.
- **tools/list**: Lists available tools for the application.
- **tools/call**: Calls a specific tool with provided arguments.

Refer to the MCP specification for detailed parameter structures for each method.

### Request Example (Initialize MCP session)
```bash
curl -X POST "http://localhost:8080/chat/mcp" \
  -H "Authorization: Bearer application-abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {}
  }'
```

### Request Example (List available tools)
```bash
curl -X POST "http://localhost:8080/chat/mcp" \
  -H "Authorization: Bearer application-abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'
```

### Response Example (List tools)
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      { "name": "search_knowledge", "description": "Search product documentation", "inputSchema": {...} }
    ]
  }
}
```

### Request Example (Call a tool)
```bash
curl -X POST "http://localhost:8080/chat/mcp" \
  -H "Authorization: Bearer application-abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "search_knowledge",
      "arguments": { "query": "return policy" }
    }
  }'
```
```

--------------------------------

### List All Model Providers

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Retrieves a list of all registered LLM providers and the model types they support. This includes providers like OpenAI, Anthropic, and AWS Bedrock.

```bash
curl "http://localhost:8080/api/provider" \
  -H "Authorization: $TOKEN"
```

--------------------------------

### Import Application

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Imports an application definition from a JSON file into a specified workspace.

```APIDOC
## POST /api/workspace/{workspace_id}/application/folder/import

### Description
Imports an application definition from a JSON file into a specified workspace.

### Method
POST

### Endpoint
`/api/workspace/{workspace_id}/application/folder/import`

### Parameters
#### Path Parameters
- **workspace_id** (string) - Required - The ID of the workspace to import into.

#### Request Body
- **file** (file) - Required - The JSON file containing the application definition.

### Request Example
```bash
# Import into another workspace
curl -X POST \
  "http://localhost:8080/api/workspace/staging/application/folder/default/import" \
  -H "Authorization: $TOKEN" \
  -F "file=@customer_support_bot.json"
```
```

--------------------------------

### OpenAI-Compatible Chat Completions

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Use this endpoint with any OpenAI SDK client by setting the base URL to MaxKB. The model parameter is ignored as MaxKB uses the application's configured model.

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/chat",
    api_key="application-abc123..."   # MaxKB application API key
)

response = client.chat.completions.create(
    model="default",   # model is ignored; MaxKB uses the application's configured model
    messages=[
        {"role": "user", "content": "Summarize the refund process"}
    ],
    stream=True
)

for chunk in response:
    print(chunk.choices[0].delta.content or "", end="", flush=True)
```

--------------------------------

### Add a Model

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Registers a new model instance within a specific workspace, including its configuration and credentials.

```APIDOC
## POST /api/workspace/{workspace_id}/model

### Description
Registers a model instance under a specified workspace. This includes providing the model's name, provider, type, specific model name, and necessary credentials.

### Method
POST

### Endpoint
`/api/workspace/{workspace_id}/model`

### Parameters
#### Path Parameters
- **workspace_id** (string) - Required - The ID of the workspace where the model will be registered.

#### Request Body
- **name** (string) - Required - The desired name for the model instance (e.g., "GPT-4o").
- **provider** (string) - Required - The identifier of the model provider (e.g., "openai_model_provider").
- **model_type** (string) - Required - The type of the model (e.g., "LLM", "Embedding").
- **model_name** (string) - Required - The specific name of the model as provided by the provider (e.g., "gpt-4o").
- **credential** (object) - Required - An object containing the credentials for the model provider.
  - **api_key** (string) - Required - The API key for authentication.
  - **api_base** (string) - Optional - The base URL for the API endpoint, if different from the default.

### Request Example (Registering an OpenAI GPT-4o model)
```bash
curl -X POST "http://localhost:8080/api/workspace/default/model" \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GPT-4o",
    "provider": "openai_model_provider",
    "model_type": "LLM",
    "model_name": "gpt-4o",
    "credential": {
      "api_key": "sk-...",
      "api_base": "https://api.openai.com/v1"
    }
  }'
```
```

--------------------------------

### Export Application

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Downloads the application definition (workflow, settings, prompts) as a JSON file for backup or cloning.

```APIDOC
## GET /api/workspace/{workspace_id}/application/{application_id}/export

### Description
Downloads the application definition (workflow, settings, prompts) as a JSON file for backup or cloning.

### Method
GET

### Endpoint
`/api/workspace/{workspace_id}/application/{application_id}/export`

### Request Example
```bash
# Export
curl -OJ \
  "http://localhost:8080/api/workspace/default/application/app-uuid-001/export" \
  -H "Authorization: $TOKEN"
```
```

--------------------------------

### MaxKB User Login API

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Authenticates a user via POST request to /api/user/login and returns a session token. This token is required for subsequent management API calls in the Authorization header.

```bash
# Login and capture token
curl -s -X POST http://localhost:8080/api/user/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "MaxKB@123.."}' | jq . 

# Response
# {
#   "code": 200,
#   "message": "success",
#   "data": { "token": "eyJ0eXAiOiJKV1..." }
# }

TOKEN="eyJ0eXAiOiJKV1..."

# Use token in subsequent requests
curl http://localhost:8080/api/workspace/default/application \
  -H "Authorization: $TOKEN"

```

--------------------------------

### Register Local Ollama Model

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Use this `curl` command to register a local Ollama model with the MaxKB API. Ensure you replace `$TOKEN` with your actual authorization token and adjust the `api_base` if your Ollama instance is not accessible via Docker's internal host.

```bash
curl -X POST "http://localhost:8080/api/workspace/default/model" \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Llama3-local",
    "provider": "ollama_model_provider",
    "model_type": "LLM",
    "model_name": "llama3",
    "credential": {
      "api_base": "http://host.docker.internal:11434"
    }
  }'
```

--------------------------------

### Publish an AI Application

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Makes an AI application publicly accessible via its access token URL. This is a necessary step before the application can be used externally.

```bash
curl -X POST \
  "http://localhost:8080/api/workspace/default/application/app-uuid-001/publish" \
  -H "Authorization: $TOKEN"
```

--------------------------------

### Extract MaxKB Offline Package

Source: https://github.com/1panel-dev/maxkb/wiki/1-安装部署

After downloading the offline package, use this command to extract it on your server. Replace the filename with your downloaded package.

```bash
# maxkb-v1.2.0-offline.tar.gz替换成下载包的名字  
tar -zxvf maxkb-v1.2.0-offline.tar.gz

```

--------------------------------

### Configure a Tool Node

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Defines a workflow node that executes a registered tool. Specify the tool ID and how its input parameters should be sourced.

```python
node_data = {
    "type": "tool-node",
    "tool_id": "tool-uuid-weather",
    "input_field_list": [
        {
            "name": "city",
            "type": "string",
            "is_required": True,
            "source": "reference",
            "value": ["parameter_extraction_node", "city"]
        }
    ],
    "is_result": False
}
```

--------------------------------

### Pull Latest MaxKB Docker Image

Source: https://github.com/1panel-dev/maxkb/wiki/1-安装部署

Before upgrading, pull the latest MaxKB Docker image to ensure you are using the most recent version.

```bash
docker pull cr2.fit2cloud.com/1panel/maxkb

```

--------------------------------

### Upload a Document

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Uploads one or more files into a knowledge base. The backend automatically chooses a splitter and schedules vectorization.

```APIDOC
## POST /api/workspace/{workspace_id}/knowledge/{knowledge_id}/document

### Description
Uploads one or more files into a knowledge base. The backend automatically chooses a splitter (PDF, DOCX, HTML, XLSX, CSV, TXT, ZIP) and schedules vectorization.

### Method
POST

### Endpoint
/api/workspace/{workspace_id}/knowledge/{knowledge_id}/document

### Parameters
#### Path Parameters
- **workspace_id** (string) - Required - The ID of the workspace.
- **knowledge_id** (string) - Required - The ID of the knowledge base.

#### Request Body
- **file** (file) - Required - The file to upload.
- **meta** (object) - Optional - Metadata for the document, e.g., `{"directly_return_similarity": 0.9, "hit_handling_method": "optimization"}`.

### Request Example
```bash
curl -X POST \
  "http://localhost:8080/api/workspace/default/knowledge/kb-uuid-001/document" \
  -H "Authorization: $TOKEN" \
  -F "file=@/path/to/manual.pdf" \
  -F 'meta={"directly_return_similarity": 0.9, "hit_handling_method": "optimization"}'
```

### Response
#### Success Response (200)
- **code** (integer) - The status code of the response.
- **data** (array) - An array of uploaded document information.
  - **id** (string) - The ID of the document.
  - **name** (string) - The name of the document.
  - **status** (string) - The status of the document (e.g., 'PENDING vectorization').
  - **char_length** (integer) - The character length of the document.
```

--------------------------------

### Debug / Test a Tool

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Runs a tool function with supplied inputs and returns the output without persisting anything. This is useful for testing tool logic before deploying it.

```APIDOC
## POST /api/workspace/{workspace_id}/tool/debug

### Description
Runs a tool function with supplied inputs and returns the output without persisting anything.

### Method
POST

### Endpoint
/api/workspace/{workspace_id}/tool/debug

### Parameters
#### Path Parameters
- **workspace_id** (string) - Required - The ID of the workspace to debug the tool in.

#### Request Body
- **code** (string) - Required - The Python code for the tool function.
- **input_field_list** (array) - Required - A list of input fields and their values for the tool.
  - **name** (string) - Required - The name of the input field.
  - **type** (string) - Required - The data type of the input field.
  - **value** (any) - Required - The value to pass to the input field.

### Request Example
```bash
curl -X POST "http://localhost:8080/api/workspace/default/tool/debug" \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d 
    {
      "code": "def main(x: int, y: int) -> int:\n    return x + y",
      "input_field_list": [
        {"name": "x", "type": "int", "value": 10},
        {"name": "y", "type": "int", "value": 32}
      ]
    }
```

### Response
#### Success Response (200)
- **code** (integer) - The HTTP status code.
- **data** (any) - The output of the tool function.

#### Response Example
```json
{ "code": 200, "data": 42 }
```
```

--------------------------------

### Create a User (Admin)

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Creates a new user account. This operation is restricted to administrators.

```APIDOC
## POST /api/user_manage

### Description
Creates a new user account. This operation is restricted to administrators.

### Method
POST

### Endpoint
/api/user_manage

### Request Body
- **username** (string) - Required - The username for the new account.
- **password** (string) - Required - The password for the new account.
- **email** (string) - Required - The email address for the new account.
- **nick_name** (string) - Optional - The display name for the user.
- **phone** (string) - Optional - The phone number for the user.
- **is_active** (boolean) - Optional - Whether the user account is active.

### Request Example
```json
{
  "username": "jdoe",
  "password": "Str0ngPass!",
  "email": "jdoe@example.com",
  "nick_name": "John Doe",
  "phone": "+1-555-0100",
  "is_active": true
}
```
```

--------------------------------

### Import / Export Knowledge Base

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Downloads the full knowledge base as a ZIP archive for backup or migration, or imports a knowledge base from a ZIP archive.

```APIDOC
## GET /api/workspace/{workspace_id}/knowledge/{knowledge_id}/export_zip, POST /api/workspace/default/knowledge/import_knowledge

### Description
Downloads the full knowledge base as a ZIP archive for backup or migration, or imports a knowledge base from a ZIP archive.

### Method
GET (export), POST (import)

### Endpoint
- Export: `/api/workspace/{workspace_id}/knowledge/{knowledge_id}/export_zip`
- Import: `/api/workspace/default/knowledge/import_knowledge`

### Parameters
#### Path Parameters (for Export)
- **workspace_id** (string) - Required - The ID of the workspace.
- **knowledge_id** (string) - Required - The ID of the knowledge base.

#### Request Body (for Import)
- **file** (file) - Required - The ZIP archive containing the knowledge base to import.

### Request Example
```bash
# Export as ZIP
curl -OJ \
  "http://localhost:8080/api/workspace/default/knowledge/kb-uuid-001/export_zip" \
  -H "Authorization: $TOKEN"

# Import from ZIP
curl -X POST \
  "http://localhost:8080/api/workspace/default/knowledge/import_knowledge" \
  -H "Authorization: $TOKEN" \
  -F "file=@knowledge_export.zip"
```
```

--------------------------------

### Configure Search Knowledge Node

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Configuration for the `search-knowledge-node` which performs vector similarity search. The `knowledge_setting` allows tuning of search parameters like `top_n` and `similarity`. The `search_mode` can be set to 'embedding', 'keywords', or 'blend'.

```python
node_data = {
    "type": "search-knowledge-node",
    "knowledge_id_list": ["kb-uuid-001", "kb-uuid-002"],
    "knowledge_setting": {
        "top_n": 5,
        "similarity": 0.6,
        "max_paragraph_char_number": 5000,
        "search_mode": "embedding"   # "embedding" | "keywords" | "blend"
    },
    "question": "{{global.question}}",
    "show_knowledge": True,
    "search_scope_type": "setting"  # "setting" | "referencing"
}

# After execution, the node exposes:
# context['data']          -> concatenated paragraph text (up to max_paragraph_char_number)
# context['paragraph_list'] -> list of matched paragraphs with similarity scores
# context['directly_return'] -> paragraphs whose similarity exceeds directly_return_similarity
```

--------------------------------

### Open a Chat Session

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Creates or retrieves a chat session ID for an application. This requires a chat token, which can be obtained from anonymous authentication or an API key.

```bash
# Using an API key as Bearer token
curl "http://localhost:8080/chat/open" \
  -H "Authorization: application-abc123..."
```

--------------------------------

### Generate an API Key for an Application

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Creates a bearer API key for programmatic access to an application's chat endpoint. This key is essential for authenticating requests to the chat API.

```bash
curl -X POST \
  "http://localhost:8080/api/workspace/default/application/app-uuid-001/application_key" \
  -H "Authorization: $TOKEN"
```

--------------------------------

### List Chat Sessions

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Retrieves a paginated list of chat sessions for a given application within a workspace. Includes metadata like user, timestamps, and token usage.

```bash
curl "http://localhost:8080/api/workspace/default/application/app-uuid-001/chat/1/20" \
  -H "Authorization: $TOKEN"
```

--------------------------------

### List All Providers

Source: https://context7.com/1panel-dev/maxkb/llms.txt

Retrieves a list of all registered LLM providers and the types of models they support, including OpenAI, Anthropic, DeepSeek, and others.

```APIDOC
## GET /api/provider

### Description
Fetches a comprehensive list of all registered Large Language Model (LLM) providers. For each provider, it details the supported model types such as LLM, Embedding, TTS, STT, TTI, and Image.

### Method
GET

### Endpoint
`/api/provider`

### Parameters
No parameters are required for this request.

### Request Example (curl)
```bash
curl "http://localhost:8080/api/provider" \
  -H "Authorization: $TOKEN"
```

### Response
#### Success Response (200)
- **code** (integer) - The status code, expected to be 200.
- **data** (array) - A list of provider objects.
  - **name** (string) - The display name of the provider (e.g., "OpenAI").
  - **provider** (string) - The internal identifier for the provider (e.g., "openai_model_provider").
  - **model_type_list** (array of strings) - A list of model types supported by the provider (e.g., ["LLM", "Embedding", "TTS"]).

#### Response Example
```json
{
  "code": 200,
  "data": [
    { "name": "OpenAI", "provider": "openai_model_provider", "model_type_list": ["LLM","Embedding","TTS","STT","TTI"] },
    { "name": "Anthropic", "provider": "anthropic_model_provider", "model_type_list": ["LLM","Image"] },
    { "name": "DeepSeek", "provider": "deepseek_model_provider", "model_type_list": ["LLM"] },
    ...
  ]
}
```
```