xanoscript-docs-expert

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

XanoScript Docs Expert

XanoScript Docs 专家技能

Overview

概述

This skill provides expert-level knowledge for working with the

xanoscript_docs

system inside the

@xano/developer-mcp

project. The project is a dual-purpose npm package: an MCP Server that serves XanoScript documentation to AI assistants, and a standalone library. The documentation lives as markdown files in

src/xanoscript_docs/

and is the primary content delivered by the

xanoscript_docs

MCP tool.

本技能提供了在

@xano/developer-mcp

项目中使用

xanoscript_docs

系统的专家级知识。该项目是一个兼具双重用途的npm包：既是为AI助手提供XanoScript文档的MCP Server，也是一个独立库。文档以Markdown文件形式存储在

src/xanoscript_docs/

目录下，是

xanoscript_docs

MCP工具提供的核心内容。

Architecture at a Glance

架构概览

src/
├── index.ts                    # MCP server entry (stdio transport)
├── lib.ts                      # Library entry (standalone usage)
├── xanoscript.ts               # Core doc logic: topic registry, file matching, content extraction
├── tools/
│   ├── index.ts                # Tool registry + dispatch (6 tools total)
│   ├── xanoscript_docs.ts      # xanoscript_docs tool: path resolution, MCP definition
│   ├── validate_xanoscript.ts  # Code validation via language server parser
│   ├── meta_api_docs.ts        # Meta API docs tool
│   ├── run_api_docs.ts         # Run API docs tool
│   ├── cli_docs.ts             # CLI docs tool
│   ├── mcp_version.ts          # Version tool
│   └── types.ts                # Shared ToolResult type
├── xanoscript_docs/            # 34 documentation topics (THE CONTENT)
│   ├── README.md               # Overview (returned when no args)
│   ├── version.json            # { "version": "2.0.0", "updated": "2025-02-06" }
│   ├── docs_index.json         # Machine-readable index with aliases, filters, constructs
│   ├── cheatsheet.md, syntax.md, quickstart.md, types.md  # Core language docs
│   ├── functions.md, database.md, tables.md, apis.md      # Construct-specific docs
│   ├── agents.md, tools.md, mcp-servers.md, triggers.md   # AI & event docs
│   ├── [16 more topic files...]
│   └── integrations/           # Sub-topic directory
│       ├── cloud-storage.md, search.md, redis.md
│       ├── external-apis.md, utilities.md
│   ...
├── meta_api_docs/              # Separate doc module for Meta API
├── run_api_docs/               # Separate doc module for Run API
└── cli_docs/                   # Separate doc module for CLI

src/
├── index.ts                    # MCP服务器入口（stdio传输）
├── lib.ts                      # 库入口（独立使用）
├── xanoscript.ts               # 核心文档逻辑：主题注册表、文件匹配、内容提取
├── tools/
│   ├── index.ts                # 工具注册表 + 调度（共6个工具）
│   ├── xanoscript_docs.ts      # xanoscript_docs工具：路径解析、MCP定义
│   ├── validate_xanoscript.ts  # 通过语言服务器解析器进行代码验证
│   ├── meta_api_docs.ts        # Meta API文档工具
│   ├── run_api_docs.ts         # Run API文档工具
│   ├── cli_docs.ts             # CLI文档工具
│   ├── mcp_version.ts          # 版本工具
│   └── types.ts                # 共享ToolResult类型
├── xanoscript_docs/            # 34个文档主题（核心内容）
│   ├── README.md               # 概述（无参数时返回）
│   ├── version.json            # { "version": "2.0.0", "updated": "2025-02-06" }
│   ├── docs_index.json         # 包含别名、过滤器、结构的机器可读索引
│   ├── cheatsheet.md, syntax.md, quickstart.md, types.md  # 核心语言文档
│   ├── functions.md, database.md, tables.md, apis.md      # 特定结构文档
│   ├── agents.md, tools.md, mcp-servers.md, triggers.md   # AI与事件文档
│   ├── [16个更多主题文件...]
│   └── integrations/           # 子主题目录
│       ├── cloud-storage.md, search.md, redis.md
│       ├── external-apis.md, utilities.md
│   ...
├── meta_api_docs/              # Meta API的独立文档模块
├── run_api_docs/               # Run API的独立文档模块
└── cli_docs/                   # CLI的独立文档模块

How the xanoscript_docs Tool Works

xanoscript_docs工具的工作原理

Request Flow

请求流程

Caller provides { topic?, file_path?, mode? }
    │
    ├── No args → Return README.md
    ├── topic="syntax" → Return syntax.md content
    ├── file_path="api/users/create.xs" → minimatch applyTo patterns → return all matching docs
    └── mode="quick_reference" → Extract only "## Quick Reference" sections
    │
    └── All responses append: "---\nDocumentation version: X.X.X"

调用者提供 { topic?, file_path?, mode? }
    │
    ├── 无参数 → 返回README.md
    ├── topic="syntax" → 返回syntax.md内容
    ├── file_path="api/users/create.xs" → 应用minimatch的applyTo模式 → 返回所有匹配文档
    └── mode="quick_reference" → 仅提取"## Quick Reference"章节
    │
    └── 所有响应追加："---\nDocumentation version: X.X.X"

Key Source Files

关键源文件

src/xanoscript.ts
— The brain of the system:

```
XANOSCRIPT_DOCS_V2
```
: Record<string, DocConfig> mapping 34 topic keys to
```
{ file, applyTo, description }
```
```
getDocsForFilePath(filePath)
```
: Uses
```
minimatch
```
to match file paths against
```
applyTo
```
glob patterns. Always includes "syntax" as a foundation topic.
```
extractQuickReference(content, topic)
```
: Finds "## Quick Reference" heading and extracts content until the next
```
## 
```
heading. Falls back to first 50 lines.
```
readXanoscriptDocsV2(docsPath, args)
```
: Main read function — decides what to return based on args.

src/tools/xanoscript_docs.ts
— The tool wrapper:

getXanoscriptDocsPath()

: Resolves docs directory — tries

dist/xanoscript_docs/

first, falls back to

src/xanoscript_docs/

xanoscriptDocs(args)

: Standalone function returning

{ documentation: string }

xanoscriptDocsTool(args)

: Returns

ToolResult

(

{ success, data?, error? }

```
xanoscriptDocsToolDefinition
```
: MCP tool schema with name, description, inputSchema.

src/tools/index.ts
— Registration:

```
toolDefinitions
```
array registers all 6 tools
```
handleTool(name, args)
```
dispatches by tool name

toMcpResponse()

converts ToolResult to MCP format:

{ content: [{ type: "text", text }], isError? }

src/xanoscript.ts
— 系统核心：

```
XANOSCRIPT_DOCS_V2
```
: Record<string, DocConfig>，将34个主题键映射到
```
{ file, applyTo, description }
```
```
getDocsForFilePath(filePath)
```
: 使用
```
minimatch
```
将文件路径与
```
applyTo
```
通配符模式匹配，始终包含"syntax"作为基础主题
```
extractQuickReference(content, topic)
```
: 查找"## Quick Reference"标题并提取内容直到下一个
```
## 
```
标题，若未找到则返回前50行
```
readXanoscriptDocsV2(docsPath, args)
```
: 主读取函数 — 根据参数决定返回内容

src/tools/xanoscript_docs.ts
— 工具封装：

getXanoscriptDocsPath()

: 解析文档目录 — 优先尝试

dist/xanoscript_docs/

， fallback到

src/xanoscript_docs/

xanoscriptDocs(args)

: 返回

{ documentation: string }

的独立函数

xanoscriptDocsTool(args)

: 返回

ToolResult

（

{ success, data?, error? }

）

```
xanoscriptDocsToolDefinition
```
: 包含名称、描述、inputSchema的MCP工具 schema

src/tools/index.ts
— 注册：

```
toolDefinitions
```
数组注册所有6个工具
```
handleTool(name, args)
```
根据工具名称调度

toMcpResponse()

将ToolResult转换为MCP格式：

{ content: [{ type: "text", text }], isError? }

Build Process

构建流程

bash

tsc && cp -r src/xanoscript_docs dist/

TypeScript compiles to

dist/

, then markdown files are copied verbatim. The docs are NOT transformed — they ship as-is.

bash

tsc && cp -r src/xanoscript_docs dist/

TypeScript编译到

dist/

目录，然后Markdown文件被原样复制。文档不会被转换 — 按原始形式发布。

Adding a New Documentation Topic

添加新文档主题

This is the most common modification. Follow these steps exactly:

这是最常见的修改操作，请严格遵循以下步骤：

Step 1: Create the Markdown File

步骤1：创建Markdown文件

Create a new

.md

file in

src/xanoscript_docs/

. For sub-topics, use the

integrations/

subdirectory pattern.

Every doc file MUST start with frontmatter:

markdown

---
applyTo: "function/*.xs, api/**/*.xs"
---

The

applyTo

value specifies which file patterns this doc applies to when using context-aware delivery. Use empty string or omit patterns for docs only accessible via explicit

topic

parameter.

在

src/xanoscript_docs/

目录下创建新的

.md

文件。子主题请使用

integrations/

子目录模式。

每个文档文件必须以frontmatter开头：

markdown

---
applyTo: "function/*.xs, api/**/*.xs"
---

applyTo

值指定了当使用上下文感知交付时，此文档适用的文件模式。若文档仅可通过显式

topic

参数访问，可使用空字符串或省略该模式。

Step 2: Register the Topic in

src/xanoscript.ts

步骤2：在

src/xanoscript.ts

中注册主题

Add an entry to the

XANOSCRIPT_DOCS_V2

object:

typescript

"my-new-topic": {
  file: "my-new-topic.md",           // Path relative to xanoscript_docs/
  applyTo: ["function/**/*.xs"],        // Glob patterns for context-aware matching
  description: "One-line description of what this doc covers",
},

For sub-topics in a directory:

typescript

"integrations/my-service": {
  file: "integrations/my-service.md",
  applyTo: [],                        // Sub-topics typically have empty applyTo
  description: "Description here",
},

在

XANOSCRIPT_DOCS_V2

对象中添加条目：

typescript

"my-new-topic": {
  file: "my-new-topic.md",           // 相对于xanoscript_docs/的路径
  applyTo: ["function/**/*.xs"],        // 上下文感知匹配的通配符模式
  description: "该文档涵盖内容的单行描述",
},

对于目录中的子主题：

typescript

"integrations/my-service": {
  file: "integrations/my-service.md",
  applyTo: [],                        // 子主题通常为空applyTo
  description: "描述内容",
},

Step 3: Update

docs_index.json

(Optional but Recommended)

步骤3：更新

docs_index.json

（可选但推荐）

Add the topic to

src/xanoscript_docs/docs_index.json

in the appropriate section:

json

"my-new-topic": {
  "file": "my-new-topic.md",
  "purpose": "Brief purpose description",
  "aliases": ["alias1", "alias2"]
}

Also update

constructs

operations

, or

tasks

sections if the new topic documents any of those.

在

src/xanoscript_docs/docs_index.json

的对应章节中添加主题：

json

"my-new-topic": {
  "file": "my-new-topic.md",
  "purpose": "简要用途描述",
  "aliases": ["alias1", "alias2"]
}

如果新主题涉及任何结构、操作或任务，也请更新

constructs

、

operations

或

tasks

章节。

Step 4: Bump Version

步骤4：更新版本

Update

src/xanoscript_docs/version.json

json

{
  "version": "2.1.0",
  "updated": "2025-03-15"
}

更新

src/xanoscript_docs/version.json

：

json

{
  "version": "2.1.0",
  "updated": "2025-03-15"
}

Step 5: Build and Test

步骤5：构建并测试

bash

npm run build    # tsc && cp -r src/xanoscript_docs dist/
npm test         # vitest run

bash

npm run build    # tsc && cp -r src/xanoscript_docs dist/
npm test         # vitest run

Documentation Authoring Conventions

文档创作规范

Read

references/doc-conventions.md

for the complete style guide. Here's the essential pattern:

完整的风格指南请查看

references/doc-conventions.md

。以下是核心模式：

Required Structure

必需结构

Every documentation file follows this skeleton:

markdown

---
applyTo: "pattern/**/*.xs"
---

每个文档文件遵循以下框架：

markdown

---
applyTo: "pattern/**/*.xs"
---

Topic Title

主题标题

TL;DR: One or two sentences summarizing the key concepts.

TL;DR: 一两句话总结核心概念。

Quick Reference

Feature	Example	Notes
...	...	...

特性	示例	说明
...	...	...

[Detailed Sections]

[详细章节]

Basic Structure

基础结构

[Minimal working example]

[最小可运行示例]

Common Patterns

常见模式

[Real-world usage examples]

[实际使用示例]

Common Mistakes

常见错误

❌ Wrong:

// incorrect code

✅ Correct:

// correct code

❌ 错误写法：

// 错误代码

✅ 正确写法：

// 正确代码

Topic	Use For
[syntax](xanoscript_docs({ topic: "syntax" }))	Filters and operators

主题	适用场景
[syntax](xanoscript_docs({ topic: "syntax" }))	过滤器与运算符

XanoScript Language Reference

XanoScript语言参考

For quick reference when writing docs, see

references/xanoscript-language.md

. Key things to remember:

编写文档时的快速参考请查看

references/xanoscript-language.md

。需要记住的关键点：

Type Names (Common Mistake Area)

类型名称（常见错误点）

Correct	WRONG
`text`	`string`
`int`	`integer`
`decimal`	`float` , `number`
`bool`	`boolean`

正确写法	错误写法
`text`	`string`
`int`	`integer`
`decimal`	`float` , `number`
`bool`	`boolean`

Filter Type Safety (Most Common Doc Error)

过滤器类型安全（最常见文档错误）

String filters and array filters are NOT interchangeable. This is the #1 source of mistakes in the docs:

Task	String Filter	Array Filter
Get length	`strlen`	`count`
Get part	`substr`	`slice`
Reverse	`split:""\|reverse\|join:""`	`reverse`

字符串过滤器和数组过滤器不可互换，这是文档中最常见的错误来源：

任务	字符串过滤器	数组过滤器
获取长度	`strlen`	`count`
获取部分内容	`substr`	`slice`
反转	`split:""\|reverse\|join:""`	`reverse`

Control Flow Keyword

控制流关键字

Always

elseif

(one word), never

else if

始终使用

elseif

（一个单词），切勿使用

else if

。

String Concatenation

字符串拼接

Use

(tilde), not

. Parentheses required around filtered values in concatenation:

($count|to_text) ~ " items"

使用

（波浪号），而非

。拼接中经过过滤的值必须加括号：

($count|to_text) ~ " items"

Modifying the MCP Tool Itself

修改MCP工具本身

For changes to how documentation is served (not the content):

若要更改文档的提供方式（而非内容）：

Changing Tool Parameters

修改工具参数

Edit

xanoscriptDocsToolDefinition

src/tools/xanoscript_docs.ts

. The

inputSchema

follows JSON Schema format.

编辑

src/tools/xanoscript_docs.ts

中的

xanoscriptDocsToolDefinition

。

inputSchema

遵循JSON Schema格式。

Changing Doc Resolution Logic

修改文档解析逻辑

Edit functions in

src/xanoscript.ts

```
getDocsForFilePath()
```
— context-aware matching logic
```
extractQuickReference()
```
— quick reference extraction
```
readXanoscriptDocsV2()
```
— main read dispatch

编辑

src/xanoscript.ts

中的函数：

```
getDocsForFilePath()
```
— 上下文感知匹配逻辑
```
extractQuickReference()
```
— 快速参考提取逻辑
```
readXanoscriptDocsV2()
```
— 主读取调度逻辑

Changing Path Resolution

修改路径解析

Edit

getXanoscriptDocsPath()

src/tools/xanoscript_docs.ts

. The fallback chain:

dist/xanoscript_docs/

→

src/xanoscript_docs/

→ default.

编辑

src/tools/xanoscript_docs.ts

中的

getXanoscriptDocsPath()

。 fallback链：

dist/xanoscript_docs/

→

src/xanoscript_docs/

→ 默认路径。

Adding a New MCP Tool

添加新MCP工具

Create
```
src/tools/my_tool.ts
```
with tool definition and handler

src/tools/index.ts

: add to

toolDefinitions

array and

handleTool

switch

Export from
```
src/lib.ts
```
if needed for standalone usage

创建
```
src/tools/my_tool.ts
```
，包含工具定义和处理函数

在

src/tools/index.ts

中注册：添加到

toolDefinitions

数组和

handleTool

分支

若需独立使用，从
```
src/lib.ts
```
导出

Testing

测试

bash

npm test                    # Run all tests
npm run test:watch          # Watch mode
npm run test:coverage       # With V8 coverage

Test files live alongside source:

src/xanoscript.test.ts

. Tests use Vitest with

describe

it

expect

patterns.

Key things to test when modifying docs:

New topics resolve correctly via

readXanoscriptDocsV2({ topic: "new-topic" })

```
applyTo
```
patterns match expected file paths via
```
getDocsForFilePath()
```
Quick reference extraction works if your doc has a
```
## Quick Reference
```
section

bash

npm test                    # 运行所有测试
npm run test:watch          # 监听模式
npm run test:coverage       # 生成V8覆盖率报告

测试文件与源文件放在一起：

src/xanoscript.test.ts

。测试使用Vitest的

describe

it

expect

模式。

修改文档时需要测试的关键点：

新主题可通过

readXanoscriptDocsV2({ topic: "new-topic" })

正确解析

```
applyTo
```
模式可通过
```
getDocsForFilePath()
```
匹配预期文件路径
若文档包含
```
## Quick Reference
```
章节，快速参考提取功能正常工作

Common Tasks Checklist

常见任务清单

Task	Files to Modify
Add new doc topic	New `.md` file + `xanoscript.ts` (XANOSCRIPT_DOCS_V2) + optionally `docs_index.json`
Edit existing doc content	Just the `.md` file in `src/xanoscript_docs/`
Change which files a doc applies to	`xanoscript.ts` → topic's `applyTo` array
Add integration sub-topic	New file in `integrations/` + register in `xanoscript.ts`
Change tool description/schema	`src/tools/xanoscript_docs.ts` → `xanoscriptDocsToolDefinition`
Change doc resolution logic	`src/xanoscript.ts` → `readXanoscriptDocsV2()` or `getDocsForFilePath()`
Update version	`src/xanoscript_docs/version.json`
Add new MCP tool (non-docs)	New file in `src/tools/` + register in `src/tools/index.ts`

任务	需要修改的文件
添加新文档主题	新的 `.md` 文件 + `xanoscript.ts` （XANOSCRIPT_DOCS_V2） + 可选 `docs_index.json`
编辑现有文档内容	仅修改 `src/xanoscript_docs/` 下对应的 `.md` 文件
修改文档适用的文件范围	`xanoscript.ts` → 主题的 `applyTo` 数组
添加集成子主题	在 `integrations/` 中创建新文件 + 在 `xanoscript.ts` 中注册
修改工具描述/schema	`src/tools/xanoscript_docs.ts` → `xanoscriptDocsToolDefinition`
修改文档解析逻辑	`src/xanoscript.ts` → `readXanoscriptDocsV2()` 或 `getDocsForFilePath()`
更新版本	`src/xanoscript_docs/version.json`
添加新MCP工具（非文档类）	在 `src/tools/` 中创建新文件 + 在 `src/tools/index.ts` 中注册

xanoscript-docs-expert

Original

Translation

XanoScript Docs Expert

XanoScript Docs 专家技能

Overview

概述

Architecture at a Glance

架构概览

How the xanoscript_docs Tool Works

xanoscript_docs工具的工作原理

Request Flow

请求流程

Key Source Files

关键源文件

Build Process

构建流程

Adding a New Documentation Topic

添加新文档主题

Step 1: Create the Markdown File

步骤1：创建Markdown文件

Step 2: Register the Topic in src/xanoscript.ts

步骤2：在src/xanoscript.ts中注册主题

Step 3: Update docs_index.json (Optional but Recommended)

步骤3：更新docs_index.json（可选但推荐）

Step 4: Bump Version

步骤4：更新版本

Step 5: Build and Test

步骤5：构建并测试

Documentation Authoring Conventions

文档创作规范

Required Structure

必需结构

Topic Title

主题标题

Quick Reference

Quick Reference

[Detailed Sections]

[详细章节]

Basic Structure

基础结构

Common Patterns

常见模式

Common Mistakes

常见错误

Related Topics

相关主题

Code Examples

代码示例

Cross-Referencing

交叉引用

File Naming

文件命名

XanoScript Language Reference

XanoScript语言参考

Type Names (Common Mistake Area)

类型名称（常见错误点）

Filter Type Safety (Most Common Doc Error)

过滤器类型安全（最常见文档错误）

Control Flow Keyword

控制流关键字

String Concatenation

字符串拼接

Modifying the MCP Tool Itself

修改MCP工具本身

Changing Tool Parameters

修改工具参数

Changing Doc Resolution Logic

修改文档解析逻辑

Changing Path Resolution

修改路径解析

Adding a New MCP Tool

添加新MCP工具

Testing

测试

Common Tasks Checklist

常见任务清单

Step 2: Register the Topic in
`src/xanoscript.ts`

步骤2：在
`src/xanoscript.ts`
中注册主题

Step 3: Update
`docs_index.json`
(Optional but Recommended)

步骤3：更新
`docs_index.json`
（可选但推荐）