Orchata MCP Tools

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)

What is 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

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)

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 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

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

MCP Tools Reference

Space Management

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
```

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.

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).

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

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

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

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

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
}

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.

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.

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.

Workflow Patterns

Pattern 1: Search for Information (Default Approach)

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"
# Then use the returned 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.

Pattern 2: Look Up Specific Data

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.

Pattern 3: Browse a Large Document

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"

Pattern 4: Add New Content

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"

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

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

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

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

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="..."`

orchata-mcp

NPX Install

Tags

SKILL.md Content

Orchata MCP Tools

What is Orchata?

Core Concepts

Spaces

Documents

Document Trees

Queries

MCP Tools Reference

Space Management

list_spaces

manage_space

Document Management

list_documents

save_document

get_document

update_document

delete_document

Query Tools

query_spaces

smart_query

Tree Visibility Tools

get_document_tree

get_tree_node

Workflow Patterns

Pattern 1: Search for Information (Default Approach)

Pattern 2: Look Up Specific Data

Pattern 3: Browse a Large Document

Pattern 4: Add New Content

Best Practices

DO

DON'T

Error Handling

Troubleshooting Tips

Quick Reference