xanoscript-docs-expert

XanoScript ドキュメントのエキスパート

概要

このスキルでは、@xano/developer-mcp プロジェクト内の xanoscript_docs システムを扱うための専門知識を提供します。このプロジェクトは 2 つの用途を持つ npm パッケージです。XanoScript のドキュメントを AI アシスタントに提供する MCP サーバーであると同時に、スタンドアロンライブラリでもあります。ドキュメントは src/xanoscript_docs/ 内の Markdown ファイルとして保存され、xanoscript_docs MCP ツールが提供する主要なコンテンツです。

アーキテクチャの概要

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 (topic="readme"; previously the no-args default)
│   ├── 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

xanoscript_docs ツールの仕組み

リクエストの流れ

Caller provides { topic?, file_path?, mode?, tier?, max_tokens?, exclude_topics? }
    │
    ├── tier="survival"|"working" → Return the pre-built tier digest (overrides everything)
    ├── mode="index" OR no topic/file_path → Return the compact topic index (~4KB)
    │       (the no-arg default; README is reachable via topic="readme")
    ├── 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"

主なソースファイル

src/xanoscript.ts — システムの中核です。

• XANOSCRIPT_DOCS_V2：34 個のトピックキーを { file, applyTo, description } に対応付ける Record<string, DocConfig>
• getDocsForFilePath(filePath)：minimatch を使用して、ファイルパスを applyTo の glob パターンと照合します。基礎となるトピックとして、常に「syntax」が含まれます。
• extractQuickReference(content, topic)：「## Quick Reference」見出しを検索し、次の「## 」見出しまでの内容を抽出します。見つからない場合は、先頭から 50 行を使用します。
• readXanoscriptDocsV2(docsPath, args)：メインの読み取り関数です。引数に応じて返す内容を決定します。

src/tools/xanoscript_docs.ts — ツールのラッパーです。

• getXanoscriptDocsPath()：ドキュメントディレクトリを解決します。まず dist/xanoscript_docs/ を試し、次に src/xanoscript_docs/ を使用します。
• xanoscriptDocs(args)：{ documentation: string } を返すスタンドアロン関数です。
• xanoscriptDocsTool(args)：ToolResult（{ success, data?, error? }）を返します。
• xanoscriptDocsToolSpec：defineTool({ inputShape, outputShape, ... }) で作成します。Zod シェイプが唯一の信頼できる情報源であり、xanoscriptDocsToolSpec.definition にクライアント向けの派生 JSON Schema が公開されます。

src/tools/index.ts — 登録処理です。

• toolSpecs マップ（5 つのツール）は、src/index.ts の McpServer.registerTool が使用する唯一の信頼できる情報源です。
• handleTool(name, args) は非同期で、toolSpecs をキーとする型付きの dispatch テーブルを介して処理を振り分けます。ハンドラーを追加せずに toolSpecs に追加すると、コンパイルエラーになります。
• toMcpResponse() は ToolResult を MCP 形式の { content: [{ type: "text", text }], isError? } に変換します。

ビルドプロセス

tsc && cp -r src/xanoscript_docs dist/

TypeScript は dist/ にコンパイルされ、その後 Markdown ファイルがそのままコピーされます。ドキュメントは変換されず、そのまま出荷されます。

新しいドキュメントトピックの追加

これは最もよくある変更です。以下の手順に正確に従ってください。

ステップ 1：Markdown ファイルを作成する

src/xanoscript_docs/ に新しい .md ファイルを作成します。サブトピックには、integrations/ サブディレクトリのパターンを使用します。

すべてのドキュメントファイルは、必ず次のフロントマターから始めます。

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

applyTo の値は、コンテキストに応じた提供でこのドキュメントを適用するファイルパターンを指定します。明示的な topic パラメーターからのみアクセスできるドキュメントの場合は、空文字列を使うか、パターンを省略します。

ステップ 2：src/xanoscript.ts にトピックを登録する

XANOSCRIPT_DOCS_V2 オブジェクトにエントリーを追加します。

"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",
},

ディレクトリ内のサブトピックの場合：

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

ステップ 3：docs_index.json を更新する（任意ですが推奨）

適切なセクションの src/xanoscript_docs/docs_index.json にトピックを追加します。

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

新しいトピックが構文要素、操作、またはタスクを説明する場合は、constructs、operations、または tasks のセクションも更新してください。

ステップ 4：バージョンを更新する

src/xanoscript_docs/version.json を更新します。

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

ステップ 5：ビルドしてテストする

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

ドキュメント作成の規約

完全なスタイルガイドについては、references/doc-conventions.md をお読みください。基本的なパターンは次のとおりです。

必須の構成

すべてのドキュメントファイルは、次のひな形に従います。

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

# Topic Title

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

## Quick Reference

| Feature | Example | Notes |
|---------|---------|-------|
| ...     | ...     | ...   |

## [Detailed Sections]

### Basic Structure
[Minimal working example]

### Common Patterns
[Real-world usage examples]

### Common Mistakes

❌ **Wrong:**
```xs
// incorrect code

✅ 正しい例：

// correct code

関連トピック

トピック	用途
[syntax](xano_xanoscript_docs({ topic: "syntax" }))	フィルターと演算子

### Code Examples

- Use `xs` language identifier for XanoScript code blocks
- Use `javascript` for frontend code, `json` for data
- Comments use `//` only (no `#` or `/* */` in XanoScript)
- Show both wrong and correct patterns with ❌/✅ markers
- Progress from simple to complex examples

### Cross-Referencing

Reference other topics using this pattern:

詳細については、xano_xanoscript_docs({ topic: "syntax" }) を参照してください。 サブトピックの場合：xano_xanoscript_docs({ topic: "integrations/redis" })

### File Naming

- Lowercase with hyphens: `unit-testing.md`, `cloud-storage.md`
- Integration sub-topics go in `integrations/` subdirectory

## XanoScript Language Reference

For quick reference when writing docs, see `references/xanoscript-language.md`. Key things to remember:

### Type Names (Common Mistake Area)

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

### Control Flow Keyword

Always `elseif` (one word), never `else if`.

### String Concatenation

Use `~` (tilde), not `+`. Parentheses required around filtered values in concatenation:
```xs
($count|to_text) ~ " items"

MCP ツール自体の変更

ドキュメントの提供方法に関する変更（コンテンツではなく）の場合：

ツールパラメーターの変更

src/tools/xanoscript_docs.ts の xanoscriptDocsToolSpec を編集します。パラメーターは Zod の inputShape に定義されています（ドキュメント用に .describe() を使用）。MCP クライアントに送信する JSON Schema は、z.toJSONSchema によって自動的に生成されます。

ドキュメント解決ロジックの変更

src/xanoscript.ts の関数を編集します。

• getDocsForFilePath() — コンテキストに応じたマッチングロジック
• extractQuickReference() — クイックリファレンスの抽出
• readXanoscriptDocsV2() — メインの読み取り処理

パス解決の変更

src/tools/xanoscript_docs.ts の getXanoscriptDocsPath() を編集します。フォールバックの順序は dist/xanoscript_docs/ → src/xanoscript_docs/ → デフォルトです。

新しい MCP ツールの追加

1. src/tools/my_tool.ts を作成します。defineTool({ name: "xano_my_tool", inputShape, outputShape, ... }) を使って仕様を作成し、ハンドラーをエクスポートします
2. src/tools/index.ts に登録します。toolSpecs マップと型付きの dispatch テーブルに追加します（ハンドラーを忘れると、TypeScript のコンパイルが失敗します）
3. スタンドアロンでの使用に必要な場合は、src/lib.ts からエクスポートします

テスト

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

テストファイルはソースの隣にあります（src/xanoscript.test.ts）。テストには describe／it／expect パターンを使う Vitest を使用します。

ドキュメントを変更する際にテストする主な項目：

• readXanoscriptDocsV2({ topic: "new-topic" }) で新しいトピックが正しく解決される
• getDocsForFilePath() で applyTo パターンが想定どおりのファイルパスにマッチする
• ドキュメントに ## Quick Reference セクションがある場合、クイックリファレンスを正しく抽出できる

よくあるタスクのチェックリスト

タスク	変更するファイル
新しいドキュメントトピックを追加	新しい .md ファイル + xanoscript.ts（XANOSCRIPT_DOCS_V2）+ 必要に応じて docs_index.json
既存のドキュメント内容を編集	src/xanoscript_docs/ 内の .md ファイルのみ
ドキュメントを適用するファイルを変更	xanoscript.ts → トピックの applyTo 配列
インテグレーションのサブトピックを追加	integrations/ 内に新しいファイルを追加 + xanoscript.ts に登録
ツールの説明／スキーマを変更	src/tools/xanoscript_docs.ts → xanoscriptDocsToolSpec（Zod の inputShape／outputShape を編集）
ドキュメント解決ロジックを変更	src/xanoscript.ts → readXanoscriptDocsV2() または getDocsForFilePath()
バージョンを更新	src/xanoscript_docs/version.json
新しい MCP ツール（ドキュメント以外）を追加	src/tools/ に新しいファイルを追加（defineTool を使用）+ src/tools/index.ts の toolSpecs と dispatch に追加