lexiang-knowledge-base

Lexiang MCP Service

Trigger scenarios: When the user explicitly mentions "Lexiang」「lexiang」「knowledge」「document", or provides a lexiangla.com link, or gives space_id、entry_id、team_id、/spaces/、/pages/ and other Lexiang identifiers, this service should be used.

Priority: When handling Lexiang-related operations,prioritize the capabilities provided by this Skill, rather than directly calling the MCP. This Skill encapsulates best practices and complete usage instructions.

When you need to call the MCP, please rely on the latest schema returned by the MCP server.

⛔ Must read (must be understood before calling):

This servicedirectly exposes all business tools(such as team_list_teams、search_kb_search , etc.), and can be called directly

Before calling, first confirm the tool parameter definitions,relying on the schema returned by the MCP

When unsure about parameters, use get_tool_schema(tool_name="xxx") to get the latest definitions

🔑 AccessToken lifecycle management

Stage 1: Token not configured

When the MCP connection fails or there is no authentication information:

Tell the user they need to obtain the Lexiang MCP access_token
Guide the user to open https://lexiangla.com/mcp to get the configuration information
After the user obtains it, help complete the mcp.json configuration (see "Quick Start")

Stage 2: Token is about to expire

When the MCP returns a normal result but includes an expiration warning:

First return this result normally
Append a reminder at the end of the result, guiding the user to renew:

⚠️ 您的乐享访问令牌即将过期。请打开以下链接自动续期（需已登录）：
https://lexiangla.com/mcp?action=renew&company_from={company_from}

Stage 3: Token has expired (401 response)

When the MCP returns 401 unauthorized:

Do not retry repeatedly
Guide the user to recreate the session:

🔒 您的乐享访问令牌已过期。请打开以下链接创建新会话：
https://lexiangla.com/mcp?action=recreate&company_from={company_from}
创建后请将新的 access_token 提供给我进行更新。

Tenant isolation rules

company_from and access_token must belong to the same tenant, tokens from different tenants cannot be mixed
OAuth does not support cross-tenant authorization
When renewing or rebuilding a token, the company_from in the URL must be consistent with the current configuration
If the user switches enterprise/tenant, the token for the corresponding tenant must be obtained again

📊 Data model

Core concepts

Concept	Description
Team	Top-level organizational unit; a team can have multiple knowledge bases (Space)
Space (knowledge base)	A container for knowledge, belonging to a certain team, containing multiple entries (Entry), with `root_entry_id` as the root node
Entry	A content unit in the knowledge base, which can be a page, folder, or file, supporting a tree structure (parent_id)
File	An entry of the attachment type, such as PDF, Word, images, etc.

Hierarchical relationships

Team → Space → Entry（树形结构，root_entry_id 为根）
                  ├── page（页面）
                  ├── folder（文件夹）
                  └── file（文件）

URL rules

The domain is fixed as https://lexiangla.com—that is, {domain} = https://lexiangla.com

⛔ company_from Not a subdomain; it can only be used as a URL query parameter!

❌ Error:https://km.lexiangla.com/pages/xxx(treating company_from as a subdomain) ❌ Error:https://abc.lexiangla.com/pages/xxx ✅ Correct:https://lexiangla.com/pages/xxx?company_from=km ✅ Correct:https://lexiangla.com/pages/xxx(when there is no company_from)

Link concatenation rules:

https://lexiangla.com/pages/{entry_id}?company_from={company_from}

If there is no company_from, use https://lexiangla.com/pages/{entry_id}directly (without adding query parameters).

company_from How to obtain(in order of priority):

The company_from query parameter in the MCP connection URL (such as the mcp?company_from=km in km）
Environment variable COMPANY_FROM
The company_from query parameter already present in the URL provided by the user
If none are available, omit this parameter

⛔ Strictly prohibited from using mcp.lexiang-app.com to concatenate any user-accessible link! This domain is only used for MCP interface calls, not as a user access address. ⛔ Strictly prohibited from concatenating company_from into a subdomain! company_from It can only be used as a URL query parameter (?company_from=xxx), and cannot be concatenated into https://{company_from}.lexiangla.com。

Resource	URL format
Team homepage	`{domain}/t/{team_id}/spaces`
Knowledge base	`{domain}/spaces/{space_id}`
Knowledge entry	`{domain}/pages/{entry_id}`

URL parsing rules

When the user provides a link, extract the ID from the URL path (ignore query parameters）：

URL path	Extraction method
`/spaces/{space_id}`	Take the part after `spaces/` as `space_id`
`/pages/{entry_id}`	Take the part after `pages/` as `entry_id`
`/t/{team_id}/spaces`	Take the part after `t/` as `team_id`

🛡️ Write operation safety rules

Core principle: Write, modify, and delete operations must be based on target information explicitly provided by the user, and the Agent is prohibited from selecting or guessing the target on its own.

🚫 Absolutely prohibited

Prohibited from traversing team/knowledge base lists and then selecting a write target on one's own
Prohibited from deciding to write based on a name that "looks suitable"
Prohibited from executing a write without confirmation

✅ Conditions under which writing is allowed (meeting any one is sufficient)

Condition	Example
The user provided an explicit URL	`"写到这里：https://lexiangla.com/spaces/xxx"`
The user provided an explicit ID	`"写入 space_id 为 xxx 的知识库"`
The user specified a name + Agent echoes back for confirmation	The Agent finds it and displays the details, and the user confirms

Tools involved in write operations

entry_create_entry、entry_import_content、entry_import_content_to_entry、block_update_block、block_update_blocks、block_create_block_descendant、block_delete_block、block_delete_block_children、block_move_blocks、entry_rename_entry、entry_move_entry、file_apply_upload、file_commit_upload、file_create_hyperlink

Read operations are not subject to this restriction

team_list_teams、team_describe_team、team_list_frequent_teams、space_list_spaces、space_describe_space、entry_list_children、block_list_block_children、search_kb_search、search_kb_embedding_search、space_list_recently_spaces、entry_list_latest_entries、entry_describe_ai_parse_content、file_describe_file、file_download_file and other read-only operations can be executed normally.

🔍 Tool discovery and invocation

This servicedirectly exposes all business tools, which can be called directly (such as team_list_teams()、search_kb_search(keyword="xxx")）。

It also provides the following auxiliary meta-tools to help discover and understand tools:

Meta-tool	Purpose
`list_tool_categories`	List all tool categories and their tool lists
`search_tools`	Search for tools by keyword or category
`get_tool_schema`	Get the complete parameter definitions of a specific tool

Standard workflow

1. 直接调用已知工具：team_list_teams()、search_kb_search(keyword="xxx") 等
2. 不确定参数时：get_tool_schema(tool_name="xxx") → 获取参数定义
3. 不确定工具名时：search_tools(query="关键词") → 找到工具名

Most commonly used tools are already listed in this Skill and can be used directly; when encountering new tools or uncertain parameters, use get_tool_schema to query.

🚀 Quick Start

Get Configuration Parameters

Visit:https://lexiangla.com/mcp

After logging in, obtain:

company_from: Your enterprise identifier
access_token: Access token (format lxmcp_xxx）

Configuration Methods

Method 1: Automatic configuration (recommended)

Please read the step instructions in setup.md and complete the configuration as directed.

Method 2: Environment variables

export COMPANY_FROM="your_company"
export LEXIANG_TOKEN="lxmcp_YOUR_TOKEN_HERE"

Method 3: Directly modify mcp.json

Edit mcp.jsonand replace ${COMPANY_FROM} and ${LEXIANG_TOKEN} with the actual values.

mcp.json Configuration Template

{
    "mcpServers": {
        "lexiang": {
            "enabled": true,
            "url": "https://mcp.lexiang-app.com/mcp?company_from=${COMPANY_FROM}",
            "transportType": "streamable-http",
            "headers": {
                "Authorization": "Bearer ${LEXIANG_TOKEN}"
            }
        }
    }
}

Verify After Installation

After configuration is complete,call immediately whoami() to perform a connectivity check and obtain user identity information:

Call whoami()
succeeds(returns user information) → show a welcome message to the user:

✅ 乐享 MCP 连接成功！

👤 当前用户：{用户姓名}
🏢 绑定乐享：{企业/租户名称}

🎉 配置已就绪，你现在可以这样使用乐享知识库：

💡 试试这样提问：
• "看看我最近访问的知识库有什么更新"
• "我要记录今天的工作内容，为我创建一个乐享文档并拟写一个模版"
• "搜索关于 XXX 的知识文档"
• "帮我总结一下这个知识库的内容：{知识库链接}"

Flexibly adjust the displayed content based on the actual fields returned by whoami .

401 error → the token is invalid or expired; guide the user to obtain it again (see "AccessToken Lifecycle Management")
Connection timeout/other errors → check whether the mcp.json configuration is correct

Encountering problems?

Problem	Solution
No response when connecting	Confirm that the URL in mcp.json includes `company_from` and is correctly formatted
401 Unauthorized	Token expired or tenant mismatch; see "AccessToken Lifecycle Management"
Parameter error	Execute `get_tool_schema(tool_name="xxx")` to get the latest parameter definitions

🎯 Intent Recognition and Clarification

Clarify the scenarios in which this Skill is used

Keyword trigger: the user mentions "乐享", "lexiang", "knowledge base", "knowledge", or "document"
Link trigger: the host of the link provided by the user is lexiangla.com
Context continuation: the user has previously clearly used Lexiang, and subsequent operations continue by default

🛡️ Write Safety Reminder

❌ Do not traverse the team/knowledge base list and then select a write target on your own
✅ Only after the user provides a URL / ID / exact name + confirmation may you write
✅ If the write target is unclear (for example, "help me write to Lexiang" or "execute it" but no knowledge base is specified), you need to ask the user to provide the specific write location
✅ Read operations (search, browse, view) are not subject to this restriction

Tool Overview

This MCP service provides the following tools,which can be called directly. When parameters are uncertain, use the values returned by get_tool_schema as authoritative.

📚 Knowledge Base Management

entry_create_entry — create documents/folders
entry_import_content — import Markdown/HTML to create new documents (⚠️ create only)
entry_import_content_to_entry — import content into an existing page (supports overwrite/append)
entry_list_latest_entries — get recently updated items
entry_rename_entry — rename an item

📎 File Management

file_apply_upload — request file upload (returns upload_url and session_id)
file_commit_upload — confirm upload completion

🧩 Block Operations

block_convert_content_to_blocks — convert Markdown/HTML to Block structure
block_create_block_descendant — Create Block structure
block_update_block — Single block update
block_update_blocks — Batch update
block_move_blocks — Move Block
block_delete_block_children — Delete child nodes
block_delete_block — Delete specified Block (including descendants)
block_describe_block — Get single Block details
block_list_block_children — Read Block content

🔍 Search and Discovery

search_kb_search — Keyword search
search_kb_embedding_search — Semantic vector search
team_list_teams — Get team list
team_describe_team — Get team details
team_list_frequent_teams — Get frequently used team list
space_list_spaces — Get knowledge base list
space_describe_space — Get knowledge base details (returns root_entry_id）
space_list_recently_spaces — Get recently visited knowledge bases

📖 Entry and Structure Browsing

entry_list_children — Browse directory structure
entry_describe_entry — Get entry metadata (excluding body text)
entry_describe_ai_parse_content — Get AI-parsed content (including body text)
entry_list_parents — Get parent path (breadcrumb)

🔗 External Content Import

file_create_hyperlink — Import external links such as WeChat official account articles

Content Search

Keyword Search vs Semantic Search

Tool	Applicable scenarios
`search_kb_search`	Exact keyword matching
`search_kb_embedding_search`	Fuzzy queries, "remember the gist but forgot the title"

Suggestion: After semantic search recall, use entry_describe_entry or entry_describe_ai_parse_content to read precisely.

Search result link format

Based on the returned target_type concatenate the link:

target_type	URL format
`kb_page`	`{domain}/pages/<target_id>`
`kb_file` / `kb_video`	`{domain}/teams/<team_id>/docs/<target_id>`

🔗 Result link generation rules (general)

Applies to all operations that return entry_id operations, including but not limited to:entry_import_content、entry_create_entry、entry_import_content_to_entry、file_commit_upload, search results, etc.

Concatenation rules

When an operation successfully returns entry_id(or target_id), when showing the access link to the user, use the {domain} concatenation defined in the "URL rules" above:

{domain}/pages/{entry_id}

⛔ Prohibited

Prohibitedto use mcp.lexiang-app.com to concatenate the user access link
Prohibitedto use the domain of the MCP connection URL (mcp.lexiang-app.com) as the user access domain
Prohibitedto concatenate company_from as a subdomain (e.g., https://{company_from}.lexiangla.com isincorrect)
Prohibitedto fabricate or guess domains; you must strictly use the {domain}

📖 Content Reading

Tool	Returned content	Purpose
`entry_describe_entry`	Entry metadata (ID, name, type, etc.)	Get basic information
`entry_describe_ai_parse_content`	Entry body content	Read the actual content for analysis

Common Operation Flows

Write a document from a knowledge base link

⚠️ Execute only when the useractively provides a knowledge base link. See "Common Use Cases > Scenario 0" below for details.

Core steps: Extract space_id → space_describe_space get root_entry_id → entry_import_content write → use {domain}/pages/{entry_id} to concatenate the access link and return it to the user.

WeChat Official Account Import

When the user provides a mp.weixin.qq.com link and the intent is "import/save/bookmark to Lexiang", use file_create_hyperlink。

If the user only wants to read or summarize the content, do not import by default.

Common Use Cases

Scenario 0: The user provided a knowledge base link, write a document

User: "Write the report to Lexiang, the link is https://lexiangla.com/spaces/16c4224607ea45ebacce6c15130a4957"

Step 1: 从 URL 提取 space_id = "16c4224607ea45ebacce6c15130a4957"
Step 2: call_tool("space_describe_space", {"space_id": "..."}) → 获取 root_entry_id
Step 3: call_tool("entry_import_content", {"space_id": "...", "parent_id": root_entry_id, "name": "报告", "content": "...", "content_type": "markdown"})
Step 4: 从返回结果取 entry_id，向用户展示访问链接：{domain}/pages/{entry_id}

Key points：space_id and parent_id must be passed at the same time;parent_id use root_entry_id to indicate writing to the root directory; in the link, {domain} see the URL rule definition above.

Scenario 1: Create a document

call_tool("entry_create_entry", {"name": "技术文档", "parent_entry_id": "abc123", "entry_type": "page"})

Scenario 2: Import Markdown

call_tool("entry_import_content", {"parent_id": "folder123", "name": "技术文档", "content": "...", "content_type": "markdown"})

Scenario 3: Create a structured Block document

call_tool("block_create_block_descendant", {
  "entry_id": "doc123",
  "descendant": [
    {"block_id": "h1", "block_type": "h1", "heading1": {"elements": [{"text_run": {"content": "项目文档"}}]}},
    {"block_id": "tip", "block_type": "callout", "callout": {"color": "#FFF3E0"}, "children": ["tip_p"]},
    {"block_id": "tip_p", "block_type": "p", "text": {"elements": [{"text_run": {"content": "重要提示内容"}}]}},
    {"block_id": "li1", "block_type": "bulleted_list", "bulleted": {"elements": [{"text_run": {"content": "功能一"}}]}}
  ],
  "children": ["h1", "tip", "li1"]
})

Scenario 4: Upload a file (3 steps)

Step 1: call_tool("file_apply_upload", {"parent_entry_id": "folder123", "name": "README.md", "size": 1024})
        → 返回 upload_url, session_id
Step 2: HTTP PUT upload_url（上传文件内容，非 MCP 调用）
Step 3: call_tool("file_commit_upload", {"session_id": "..."})

Scenario 5: Read Block content

call_tool("block_list_block_children", {"entry_id": "abc123", "with_descendants": true})

Scenario 6: Batch update Blocks

call_tool("block_update_blocks", {
  "entry_id": "abc123",
  "updates": {
    "actual_block_id": {
      "update_text_elements": {
        "elements": [{"text_run": {"content": "更新后的内容"}}]
      }
    }
  }
})

Core Rules of Block Structure

🍃 Leaf nodes (cannot have children)

Heading blocks: h1, h2, h3, h4, h5
Code block: code
Image block: image
Divider: divider
Diagram blocks: mermaid, plantuml

📦 Container nodes (children must be specified)

Callout: callout
Table: table, table_cell
Column layout: column_list, column
Toggle block: toggle

Detailed description: For complete Block types and field definitions, see references/block-schema.md。

⚠️ Core Notes

Block ID mapping：block_id is a client-side temporary ID; the server returns the actual ID mapping
Leaf node restrictions: Headings, code blocks, images, etc. do not support the children field
Container node requirements: callout, table, column_list, etc. must specify children
File upload size: The exact file size (in bytes) must be obtained
_mcp_fields optimization: All tools support the _mcp_fields parameter to select returned fields and reduce token consumption

More details: See references/common-errors.md and references/markdown-import.md。

Auxiliary Resources

Reference documents (references/ directory)

Document	Description
`block-schema.md`	Complete description of Block types
`mcp-examples.md`	Examples of complex Block structures
`markdown-to-block.md`	Guide to converting Markdown to Blocks
`block-update.md`	Methods for batch updating Blocks
`content-reorganize.md`	Document structure reorganization
`folder-sync.md`	Folder synchronization solution
`markdown-import.md`	Detailed explanation of Markdown import
`common-errors.md`	Troubleshooting common errors
`skill-maintenance.md`	Maintenance and feedback process

Auxiliary scripts (scripts/ directory)

Script	Description
`sync-folder.ts`	Incremental folder synchronization
`block-helper.ts`	Block building auxiliary tool
`mcp-validator.ts`	MCP parameter validation

❓ Questions and Troubleshooting

When encountering problems, please first consult references/common-errors.md。

📮 Maintenance and Feedback

For the Issue feedback process and the Skill self-evolution mechanism, see references/skill-maintenance.md。