orchata-mcp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Orchata MCP Tools

Orchata MCP 工具

Use this skill when you have access to Orchata MCP server tools in your environment (Claude Desktop, MCP-compatible clients).

Use when:

You can call MCP functions like
```
list_spaces
```
,
```
query_spaces
```
, etc.
You need programmatic access to knowledge bases
You need tree-based document navigation
You're integrating Orchata operations into agent workflows

Don't use when:

You need to run terminal commands (use
```
orchata-cli
```
skill instead)
You need batch file operations (use
```
orchata-cli
```
skill instead)

当你的环境中可以访问Orchata MCP服务器工具时（如Claude Desktop、兼容MCP的客户端），请使用此技能。

适用场景：

你可以调用
```
list_spaces
```
、
```
query_spaces
```
等MCP函数
你需要以编程方式访问知识库
你需要基于树形结构的文档导航功能
你正在将Orchata操作集成到Agent工作流中

不适用场景：

你需要运行终端命令（请改用
```
orchata-cli
```
技能）
你需要进行批量文件操作（请改用
```
orchata-cli
```
技能）

What is Orchata?

什么是Orchata？

Orchata is a knowledge management platform that:

Organizes documents into Spaces - Logical containers for related content
Uses tree-based indexing - Documents are parsed into hierarchical structures with sections, summaries, and page ranges
Provides semantic search - Find relevant content using natural language queries
Exposes MCP tools - AI assistants can directly manage and query knowledge bases

Orchata是一个知识管理平台，具备以下特性：

将文档组织为Spaces - 用于存放相关内容的逻辑容器
采用树形索引 - 文档会被解析为包含章节、摘要和页码范围的层级结构
提供语义搜索 - 使用自然语言查询查找相关内容
开放MCP工具 - AI助手可直接管理和查询知识库

Core Concepts

核心概念

Spaces

A Space is a container for related documents. Think of it as a folder with semantic search capabilities.

Each space has a
```
name
```
,
```
description
```
, and optional
```
icon
```
Descriptions are used by
```
smart_query
```
to recommend relevant spaces
Spaces can be archived (soft-deleted)

Space是存放相关文档的容器，可以将其视为具备语义搜索能力的文件夹。

每个Space都有
```
name
```
（名称）、
```
description
```
（描述）和可选的
```
icon
```
（图标）
描述信息会被
```
smart_query
```
用于推荐相关的Space
Spaces可以被归档（软删除）

Documents

文档

A Document is content within a space. Supported formats include:

PDF (text-based and scanned with OCR)
Word documents (.docx)
Excel spreadsheets (.xlsx)
PowerPoint presentations (.pptx)
Markdown files (.md)
Plain text files (.txt)
Images (PNG, JPG, etc.)

Document Status:

Status	Description
`PENDING`	Uploaded, waiting for processing
`PROCESSING`	Being parsed and indexed
`COMPLETED`	Ready for queries
`FAILED`	Processing error occurred

Important: Only query documents with

status: "COMPLETED"

. Other statuses won't return results.

Document是Space中的内容，支持的格式包括：

PDF（基于文本或经OCR识别的扫描件）
Word文档（.docx）
Excel电子表格（.xlsx）
PowerPoint演示文稿（.pptx）
Markdown文件（.md）
纯文本文件（.txt）
图片（PNG、JPG等）

文档状态：

状态	描述
`PENDING`	已上传，等待处理
`PROCESSING`	正在解析和索引
`COMPLETED`	可进行查询
`FAILED`	处理过程中出现错误

重要提示： 仅查询状态为

status: "COMPLETED"

的文档，其他状态的文档不会返回结果。

Document Trees

文档树

Documents are indexed into hierarchical tree structures:

Each tree has nodes representing sections/chapters
Nodes contain:
```
title
```
,
```
summary
```
,
```
startPage
```
,
```
endPage
```
,
```
textContent
```
Trees enable precise navigation of large documents

文档会被索引为层级树形结构：

每个树的节点代表章节或小节
节点包含：
```
title
```
（标题）、
```
summary
```
（摘要）、
```
startPage
```
（起始页码）、
```
endPage
```
（结束页码）、
```
textContent
```
（文本内容）
树形结构支持对大型文档进行精准导航

Queries

查询工具

Two types of queries are available:

query_spaces
- Search document content using tree-based reasoning
smart_query
- Discover which spaces are relevant for a query

提供两种类型的查询：

query_spaces
- 使用树形推理搜索文档内容
smart_query
- 发现与查询内容相关的Spaces

MCP Tools Reference

MCP工具参考

Space Management

Space管理

list_spaces

List all knowledge spaces in the organization.

text

list_spaces
list_spaces with status="active"
list_spaces with page=1 pageSize=20

Parameters:

```
page
```
(number, optional): Page number (default: 1)
```
pageSize
```
(number, optional): Items per page (default: 10)
```
status
```
(string, optional): Filter by
```
active
```
,
```
archived
```
, or
```
all
```

列出组织中的所有知识Space。

text

list_spaces
list_spaces with status="active"
list_spaces with page=1 pageSize=20

参数：

```
page
```
（数字，可选）：页码（默认值：1）
```
pageSize
```
（数字，可选）：每页显示数量（默认值：10）
```
status
```
（字符串，可选）：按状态过滤，可选值为
```
active
```
、
```
archived
```
或
```
all
```

manage_space

Create, get, update, or delete a space.

text

manage_space with action="create" name="Product Docs" description="Technical documentation"
manage_space with action="create" name="Legal" description="Case files" icon="briefcase"
manage_space with action="get" id="space_abc123"
manage_space with action="update" id="space_abc123" description="Updated description"
manage_space with action="delete" id="space_abc123"

Parameters:

```
action
```
(string, required):
```
create
```
,
```
get
```
,
```
update
```
, or
```
delete
```
```
id
```
(string): Space ID (required for get/update/delete)
```
name
```
(string): Space name (required for create)
```
description
```
(string, optional): Space description
```
icon
```
(string, optional): Icon name. Defaults to "folder"
```
slug
```
(string, optional): URL-friendly identifier
```
isArchived
```
(boolean, optional): Archive status (for update)

Valid Icons:

folder

book

file-text

database

package

archive

briefcase

inbox

layers

box

If an invalid icon is provided, the tool returns an error with the list of valid options.

创建、获取、更新或删除Space。

text

manage_space with action="create" name="Product Docs" description="Technical documentation"
manage_space with action="create" name="Legal" description="Case files" icon="briefcase"
manage_space with action="get" id="space_abc123"
manage_space with action="update" id="space_abc123" description="Updated description"
manage_space with action="delete" id="space_abc123"

参数：

```
action
```
（字符串，必填）：
```
create
```
、
```
get
```
、
```
update
```
或
```
delete
```
```
id
```
（字符串）：Space ID（get/update/delete操作必填）
```
name
```
（字符串）：Space名称（create操作必填）
```
description
```
（字符串，可选）：Space描述
```
icon
```
（字符串，可选）：图标名称，默认值为"folder"
```
slug
```
（字符串，可选）：URL友好的标识符
```
isArchived
```
（布尔值，可选）：归档状态（用于update操作）

有效图标：

folder

book

file-text

database

package

archive

briefcase

inbox

layers

box

如果提供无效图标，工具会返回错误并列出所有有效选项。

Document Management

文档管理

list_documents

List documents in a space.

text

list_documents with spaceId="space_abc123"
list_documents with spaceId="space_abc123" status="completed"
list_documents with spaceId="space_abc123" status="all"

Parameters:

```
spaceId
```
(string, required): Space ID
```
page
```
(number, optional): Page number
```
pageSize
```
(number, optional): Items per page (max: 100)
```
status
```
(string, optional): Filter by status. Values:
```
pending
```
,
```
processing
```
,
```
completed
```
,
```
failed
```
, or
```
all
```
. Omitting returns all documents.

Note: Status values are case-insensitive (

completed

and

COMPLETED

both work).

列出指定Space中的文档。

text

list_documents with spaceId="space_abc123"
list_documents with spaceId="space_abc123" status="completed"
list_documents with spaceId="space_abc123" status="all"

参数：

```
spaceId
```
（字符串，必填）：Space ID
```
page
```
（数字，可选）：页码
```
pageSize
```
（数字，可选）：每页显示数量（最大值：100）
```
status
```
（字符串，可选）：按状态过滤，可选值为
```
pending
```
、
```
processing
```
、
```
completed
```
、
```
failed
```
或
```
all
```
。省略该参数将返回所有文档。

注意： 状态值不区分大小写（

completed

和

COMPLETED

均有效）。

save_document

Upload or upsert documents (single or batch).

Single document:

text

save_document with spaceId="space_abc123" filename="guide.md" content="# Guide\n\nContent here..."

Batch upload:

text

save_document with spaceId="space_abc123" documents=[{"filename": "doc1.md", "content": "..."}, {"filename": "doc2.md", "content": "..."}]

Parameters:

```
spaceId
```
(string, required): Space ID
```
filename
```
(string): Filename (required for single)
```
content
```
(string): Content (required for single)
```
documents
```
(array, optional): Array of
```
{filename, content, metadata}
```
for batch
```
metadata
```
(object, optional): Custom key-value pairs

上传或更新文档（单个或批量）。

单个文档：

text

save_document with spaceId="space_abc123" filename="guide.md" content="# Guide\n\nContent here..."

批量上传：

text

save_document with spaceId="space_abc123" documents=[{"filename": "doc1.md", "content": "..."}, {"filename": "doc2.md", "content": "..."}]

参数：

```
spaceId
```
（字符串，必填）：Space ID
```
filename
```
（字符串）：文件名（单个文档上传必填）
```
content
```
（字符串）：内容（单个文档上传必填）
```
documents
```
（数组，可选）：批量上传的文档数组，每个元素为
```
{filename, content, metadata}
```
```
metadata
```
（对象，可选）：自定义键值对

get_document

Get document content by ID or filename. Returns processed markdown text.

text

get_document with spaceId="space_abc123" id="doc_xyz789"
get_document with spaceId="space_abc123" filename="guide.md"
get_document with spaceId="*" filename="guide.md"

Parameters:

```
spaceId
```
(string, required): Space ID, or
```
*
```
to search all spaces (requires filename)
```
id
```
(string, optional): Document ID
```
filename
```
(string, optional): Filename

Notes:

Either
```
id
```
or
```
filename
```
is required
Use
```
spaceId="*"
```
to search all spaces when you know the filename but not the space
For completed documents, returns the extracted markdown text (not raw PDF binary)
When using
```
*
```
, the response includes the
```
spaceId
```
where the document was found

通过ID或文件名获取文档内容，返回处理后的Markdown文本。

text

get_document with spaceId="space_abc123" id="doc_xyz789"
get_document with spaceId="space_abc123" filename="guide.md"
get_document with spaceId="*" filename="guide.md"

参数：

```
spaceId
```
（字符串，必填）：Space ID，或使用
```
*
```
搜索所有Space（需指定filename）
```
id
```
（字符串，可选）：文档ID
```
filename
```
（字符串，可选）：文件名

注意事项：

必须指定
```
id
```
或
```
filename
```
其中一个
当你知道文件名但不知道所属Space时，使用
```
spaceId="*"
```
搜索所有Space
对于已完成处理的文档，返回提取后的Markdown文本（而非原始PDF二进制数据）
使用
```
*
```
时，响应结果会包含文档所在的
```
spaceId
```

update_document

Update document content or metadata.

text

update_document with spaceId="space_abc123" id="doc_xyz789" content="New content..."
update_document with spaceId="space_abc123" id="doc_xyz789" append=true content="Additional content"

Parameters:

```
spaceId
```
(string, required): Space ID
```
id
```
(string, required): Document ID
```
content
```
(string, optional): New content
```
metadata
```
(object, optional): New metadata
```
append
```
(boolean, optional): Append instead of replace
```
separator
```
(string, optional): Separator for append mode

更新文档内容或元数据。

text

update_document with spaceId="space_abc123" id="doc_xyz789" content="New content..."
update_document with spaceId="space_abc123" id="doc_xyz789" append=true content="Additional content"

参数：

```
spaceId
```
（字符串，必填）：Space ID
```
id
```
（字符串，必填）：文档ID
```
content
```
（字符串，可选）：新内容
```
metadata
```
（对象，可选）：新元数据
```
append
```
（布尔值，可选）：是否追加内容而非替换
```
separator
```
（字符串，可选）：追加模式下的分隔符

delete_document

Permanently delete a document.

text

delete_document with spaceId="space_abc123" id="doc_xyz789"

Parameters:

```
spaceId
```
(string, required): Space ID
```
id
```
(string, required): Document ID

永久删除文档。

text

delete_document with spaceId="space_abc123" id="doc_xyz789"

参数：

```
spaceId
```
（字符串，必填）：Space ID
```
id
```
（字符串，必填）：文档ID

Query Tools

查询工具

query_spaces

Search documents across one or more spaces using tree-based reasoning.

text

query_spaces with query="How do I authenticate API requests?"
query_spaces with query="installation guide" spaceIds="space_abc123"
query_spaces with query="error handling" spaceIds=["space_abc", "space_def"] topK=10

Parameters:

```
query
```
(string, required): Natural language search query
```
spaceIds
```
(string or array, optional): Space ID(s) to search. Omit or use
```
*
```
for all spaces
```
topK
```
(number, optional): Maximum results (default: 10)
```
compact
```
(boolean, optional): Use compact format (default: false). See When to Use Compact below.

When to Use Compact:

Mode	When to use	What you get
`compact=false` (default)	Most queries. Any time you need actual data, facts, numbers, dates, or details from documents.	Full results with document metadata, tree context, page ranges, and complete content.
`compact=true`	Broad discovery queries where you only need to know which documents are relevant, not their content.	Minimal results: just content snippet, source filename, and score.

Rule of thumb: Default to

compact=false

. Only use

compact=true

when you're browsing/surveying and don't need the actual content yet.

Response (compact=true format):

json

{
  "results": [
    {
      "content": "Relevant text content...",
      "source": "filename.pdf",
      "score": 0.95
    }
  ],
  "total": 5
}

使用树形推理在一个或多个Space中搜索文档。

text

query_spaces with query="How do I authenticate API requests?"
query_spaces with query="installation guide" spaceIds="space_abc123"
query_spaces with query="error handling" spaceIds=["space_abc", "space_def"] topK=10

参数：

```
query
```
（字符串，必填）：自然语言搜索查询
```
spaceIds
```
（字符串或数组，可选）：要搜索的Space ID。省略或使用
```
*
```
表示搜索所有Space
```
topK
```
（数字，可选）：最大返回结果数（默认值：10）
```
compact
```
（布尔值，可选）：是否使用紧凑格式（默认值：false）。请查看下方的何时使用紧凑格式。

何时使用紧凑格式：

模式	使用场景	返回内容
`compact=false` （默认）	大多数查询场景。当你需要从文档中获取实际数据、事实、数字、日期或详细信息时使用。	完整结果，包含文档元数据、树形上下文、页码范围和完整内容。
`compact=true`	广泛的发现类查询，你只需要知道哪些文档相关，不需要查看具体内容时使用。	精简结果：仅包含内容片段、来源文件名和匹配分数。

经验法则： 默认使用

compact=false

。仅当你只是浏览或调研、暂时不需要实际内容时，才使用

compact=true

。

响应（compact=true格式）：

json

{
  "results": [
    {
      "content": "Relevant text content...",
      "source": "filename.pdf",
      "score": 0.95
    }
  ],
  "total": 5
}

smart_query

Discover which spaces are relevant for a query using LLM reasoning.

text

smart_query with query="How do I install the SDK?"
smart_query with query="billing questions" maxSpaces=3

Parameters:

```
query
```
(string, required): Query to find relevant spaces for
```
maxSpaces
```
(number, optional): Maximum spaces to return (default: 5)

Response:

json

{
  "query": "How do I install the SDK?",
  "relevantSpaces": [
    {"spaceId": "space_abc123", "relevance": "Contains SDK installation guides"},
    {"spaceId": "space_def456", "relevance": "Has developer tutorials"}
  ],
  "totalFound": 2
}

Use case: When you don't know which space to search, use

smart_query

first to discover relevant spaces, then use

query_spaces

with those space IDs.

使用LLM推理发现与查询内容相关的Spaces。

text

smart_query with query="How do I install the SDK?"
smart_query with query="billing questions" maxSpaces=3

参数：

```
query
```
（字符串，必填）：用于查找相关Space的查询语句
```
maxSpaces
```
（数字，可选）：最大返回Space数量（默认值：5）

响应：

json

{
  "query": "How do I install the SDK?",
  "relevantSpaces": [
    {"spaceId": "space_abc123", "relevance": "Contains SDK installation guides"},
    {"spaceId": "space_def456", "relevance": "Has developer tutorials"}
  ],
  "totalFound": 2
}

使用场景： 当你不知道应该搜索哪个Space时，先使用

smart_query

发现相关Space，再使用这些Space ID调用

query_spaces

。

Tree Visibility Tools

树形结构浏览工具

These tools let you explore the hierarchical structure of indexed documents.

这些工具用于探索已索引文档的层级结构。

get_document_tree

Get the tree structure of a document showing sections, summaries, and page ranges.

text

get_document_tree with spaceId="space_abc123" documentId="doc_xyz789"

Parameters:

```
spaceId
```
(string, required): Space ID
```
documentId
```
(string, required): Document ID

Response:

json

{
  "documentId": "doc_xyz789",
  "totalPages": 45,
  "totalNodes": 12,
  "nodes": [
    {
      "nodeId": "0001",
      "title": "Introduction",
      "summary": "Overview of the system architecture...",
      "pages": "1-5",
      "depth": 0
    },
    {
      "nodeId": "0002",
      "title": "Installation",
      "summary": "Step-by-step installation guide...",
      "pages": "6-12",
      "depth": 0
    }
  ]
}

Use case: Use this to understand a document's structure before drilling into specific sections.

获取文档的树形结构，展示章节、摘要和页码范围。

text

get_document_tree with spaceId="space_abc123" documentId="doc_xyz789"

参数：

```
spaceId
```
（字符串，必填）：Space ID
```
documentId
```
（字符串，必填）：文档ID

响应：

json

{
  "documentId": "doc_xyz789",
  "totalPages": 45,
  "totalNodes": 12,
  "nodes": [
    {
      "nodeId": "0001",
      "title": "Introduction",
      "summary": "Overview of the system architecture...",
      "pages": "1-5",
      "depth": 0
    },
    {
      "nodeId": "0002",
      "title": "Installation",
      "summary": "Step-by-step installation guide...",
      "pages": "6-12",
      "depth": 0
    }
  ]
}

使用场景： 在深入查看具体章节之前，使用此工具了解文档的整体结构。

get_tree_node

Get the full text content of a specific tree node/section.

text

get_tree_node with documentId="doc_xyz789" nodeId="0002"

Parameters:

```
documentId
```
(string, required): Document ID
```
nodeId
```
(string, required): Node ID from the tree structure

Response:

json

{
  "documentId": "doc_xyz789",
  "filename": "manual.pdf",
  "nodeId": "0002",
  "title": "Installation",
  "summary": "Step-by-step installation guide...",
  "pages": "6-12",
  "depth": 0,
  "content": "## Installation\n\nTo install the software, follow these steps:\n\n1. Download the installer...\n\n..."
}

Use case: After viewing the tree structure, use this to read the full content of a specific section.

获取特定树形节点/章节的完整文本内容。

text

get_tree_node with documentId="doc_xyz789" nodeId="0002"

参数：

```
documentId
```
（字符串，必填）：文档ID
```
nodeId
```
（字符串，必填）：树形结构中的节点ID

响应：

json

{
  "documentId": "doc_xyz789",
  "filename": "manual.pdf",
  "nodeId": "0002",
  "title": "Installation",
  "summary": "Step-by-step installation guide...",
  "pages": "6-12",
  "depth": 0,
  "content": "## Installation\n\nTo install the software, follow these steps:\n\n1. Download the installer...\n\n..."
}

使用场景： 查看树形结构后，使用此工具阅读特定章节的完整内容。

Workflow Patterns

工作流模式

Pattern 1: Search for Information (Default Approach)

模式1：搜索信息（默认方法）

For most questions, a single
query_spaces
call is all you need. Start here before trying multi-step workflows.

text

query_spaces with query="your question"

This searches all spaces with full details (compact=false by default). One call, done.

If you want to narrow to specific spaces:

text

query_spaces with query="your question" spaceIds="known_space_id"

If you truly don't know which spaces exist:

text

smart_query with query="your question"

对于大多数问题，只需调用一次
query_spaces
即可。在尝试多步骤工作流之前，先从这里开始。

text

query_spaces with query="your question"

此调用会搜索所有Space并返回完整详情（默认compact=false）。一次调用即可完成。

如果你想缩小到特定Space：

text

query_spaces with query="your question" spaceIds="known_space_id"

如果你完全不知道有哪些Space：

text

smart_query with query="your question"

Then use the returned spaceIds:

然后使用返回的spaceIds：

query_spaces with query="your question" spaceIds=["returned_space_id"]


> **Avoid over-searching.** The multi-step workflow (`smart_query` -> `query_spaces` -> `get_document_tree` -> `get_tree_node`) is rarely necessary. For most questions, a single `query_spaces` call returns the answer directly. Only escalate to tree browsing if results are insufficient.

query_spaces with query="your question" spaceIds=["returned_space_id"]


> **避免过度搜索。** 多步骤工作流（`smart_query` -> `query_spaces` -> `get_document_tree` -> `get_tree_node`）很少需要。对于大多数问题，一次`query_spaces`调用就能直接返回答案。只有当结果不够充分时，才需要使用树形浏览工具。

Pattern 2: Look Up Specific Data

模式2：查找特定数据

When looking for specific facts, numbers, dates, names, or details:

text

query_spaces with query="total amount on invoice #1234"

The default

compact=false

returns full content with document metadata, so you get the actual data you need in one step. Do not use

compact=true

for data lookups -- it strips the detail you need.

当你需要查找特定事实、数字、日期、名称或详细信息时：

text

query_spaces with query="total amount on invoice #1234"

默认的

compact=false

会返回包含文档元数据的完整内容，因此你可以一步获取所需的实际数据。不要使用

compact=true

进行数据查找——它会剥离你需要的详细信息。

Pattern 3: Browse a Large Document

模式3：浏览大型文档

When you need to navigate a large document's structure:

Get the document structure:

text

get_document_tree with spaceId="space_id" documentId="doc_id"

Identify relevant sections from the node titles and summaries

Read specific sections:

text

get_tree_node with documentId="doc_id" nodeId="relevant_node_id"

当你需要导航大型文档的结构时：

获取文档结构：

text

get_document_tree with spaceId="space_id" documentId="doc_id"

从节点标题和摘要中识别相关章节

阅读特定章节：

text

get_tree_node with documentId="doc_id" nodeId="relevant_node_id"

Pattern 4: Add New Content

模式4：添加新内容

When adding documents to a knowledge base:

Find or create the appropriate space:

text

list_spaces
# or
manage_space with action="create" name="New Space" description="..."

Upload the content:

text

save_document with spaceId="space_id" filename="document.md" content="..."

Wait for processing (status will change from PENDING -> PROCESSING -> COMPLETED)

Verify it's ready:

text

list_documents with spaceId="space_id" status="COMPLETED"

当你需要向知识库添加文档时：

查找或创建合适的Space：

text

list_spaces
# 或
manage_space with action="create" name="New Space" description="..."

上传内容：

text

save_document with spaceId="space_id" filename="document.md" content="..."

等待处理完成（状态会从PENDING -> PROCESSING -> COMPLETED）

验证文档已准备就绪：

text

list_documents with spaceId="space_id" status="COMPLETED"

Best Practices

最佳实践

DO

建议做法

Start with a single
query_spaces
call - it usually has the answer in one step
Use
compact=false
(the default) for most queries - you get full content and context
Check document status before querying - only
```
COMPLETED
```
documents are searchable
Use descriptive queries - natural language works best
Use tree tools for large documents - navigate structure instead of reading everything
Write good space descriptions - they're used by
```
smart_query
```
for discovery

从单次
query_spaces
调用开始——通常一次调用就能得到答案
大多数查询使用
compact=false
（默认值）——你会获得完整内容和上下文
查询前检查文档状态——只有
```
COMPLETED
```
状态的文档可被搜索
使用描述性查询语句——自然语言效果最佳
对大型文档使用树形工具——通过导航结构代替通读全文
编写清晰的Space描述——
```
smart_query
```
会使用这些描述进行Space发现

DON'T

不建议做法

Don't over-search - avoid multi-step workflows when a single
```
query_spaces
```
call suffices
Don't use
compact=true
for data lookups - it strips the content you need; only use it for broad discovery
Don't query PENDING/PROCESSING documents - they won't return results
Don't use very short queries - more context = better results
Don't forget to check processing status after uploading new documents

不要过度搜索——当单次
```
query_spaces
```
调用足够时，避免使用多步骤工作流
不要在数据查找时使用
compact=true
——它会剥离你需要的内容；仅在广泛发现场景中使用
不要查询PENDING/PROCESSING状态的文档——这些文档不会返回结果
不要使用过短的查询语句——提供更多上下文能得到更好的结果
上传新文档后不要忘记检查处理状态

Error Handling

错误处理

Common errors and solutions:

Error	Cause	Solution
"Document not found"	Wrong ID or no access	Verify the document ID with `list_documents`
"Space not found"	Wrong ID or archived	Use `list_spaces` to find valid space IDs
Empty search results	Document not COMPLETED or no matches	Check document status; try broader query
"Tree not found"	Document uses vector indexing or not processed	Check if document status is COMPLETED
"Invalid icon"	Icon name not in allowed list	Use one of: folder, book, file-text, database, package, archive, briefcase, inbox, layers, box
"No text content cached"	Tree node content not cached	This is normal for structural nodes; use `get_document` for full content

常见错误及解决方案：

错误	原因	解决方案
"Document not found"	ID错误或无访问权限	使用 `list_documents` 验证文档ID
"Space not found"	ID错误或Space已归档	使用 `list_spaces` 查找有效的Space ID
搜索结果为空	文档未处于COMPLETED状态或无匹配内容	检查文档状态；尝试更宽泛的查询语句
"Tree not found"	文档使用向量索引或未完成处理	检查文档状态是否为COMPLETED
"Invalid icon"	图标名称不在允许列表中	使用以下有效图标之一：folder, book, file-text, database, package, archive, briefcase, inbox, layers, box
"No text content cached"	树形节点内容未被缓存	这对于结构性节点是正常现象；使用 `get_document` 获取完整内容

Troubleshooting Tips

故障排除技巧

If
save_document
fails:

Verify the space exists with
```
manage_space with action="get" id="..."
```
Ensure content is valid text/markdown
Check that the space is not archived

If
list_documents
returns 0 results:

Try
```
status="all"
```
or omit the status parameter entirely
Verify the spaceId is correct with
```
list_spaces
```
Check if documents are still processing (status="processing")

If
get_tree_node
returns no content:

Some nodes are structural and don't have cached text content
Use
```
get_document
```
to get the full processed document text instead
Or use
```
query_spaces
```
to search for specific content

如果
save_document
调用失败：

使用
```
manage_space with action="get" id="..."
```
验证Space是否存在
确保内容是有效的文本/Markdown格式
检查Space是否未被归档

如果
list_documents
返回0条结果：

尝试使用
```
status="all"
```
或完全省略status参数
使用
```
list_spaces
```
验证spaceId是否正确
检查文档是否仍在处理中（status="processing"）

如果
get_tree_node
返回无内容：

部分节点是结构性的，没有缓存文本内容
使用
```
get_document
```
获取完整的处理后文档文本
或使用
```
query_spaces
```
搜索特定内容

Quick Reference

快速参考

Task	MCP Tool	Example
List all spaces	`list_spaces`	`list_spaces with status="active"`
Create a space	`manage_space`	`manage_space with action="create" name="Docs"`
Get space	`manage_space`	`manage_space with action="get" id="space_123"`
List documents	`list_documents`	`list_documents with spaceId="space_123"`
Upload content	`save_document`	`save_document with spaceId="..." content="..."`
Get document text	`get_document`	`get_document with spaceId="..." id="..."`
Search content	`query_spaces`	`query_spaces with query="..."`
Find relevant spaces	`smart_query`	`smart_query with query="..."`
View doc structure	`get_document_tree`	`get_document_tree with spaceId="..." documentId="..."`
Read a section	`get_tree_node`	`get_tree_node with documentId="..." nodeId="..."`

任务	MCP工具	示例
列出所有Space	`list_spaces`	`list_spaces with status="active"`
创建Space	`manage_space`	`manage_space with action="create" name="Docs"`
获取Space信息	`manage_space`	`manage_space with action="get" id="space_123"`
列出文档	`list_documents`	`list_documents with spaceId="space_123"`
上传内容	`save_document`	`save_document with spaceId="..." content="..."`
获取文档文本	`get_document`	`get_document with spaceId="..." id="..."`
搜索内容	`query_spaces`	`query_spaces with query="..."`
查找相关Space	`smart_query`	`smart_query with query="..."`
查看文档结构	`get_document_tree`	`get_document_tree with spaceId="..." documentId="..."`
阅读章节内容	`get_tree_node`	`get_tree_node with documentId="..." nodeId="..."`