Tool reference

This document is the reference for every tool cjdrift exposes. Each section lists the tool's MCP method name, its input schema (JSON Schema 2020-12), and the shape of the result it returns.

The result for every tool is a single TextBlock whose text is a JSON object. The shape of that object is documented below under "Result".

cangjie_apis

Fuzzy search the offline Cangjie 1.1.3 standard-library index.

Input

Field	Type	Required	Default	Description
query	string	yes	—	Free-text search. Matches against type name, member name, package name, and signature.
limit	integer	no	10	Max results to return. Hard cap 50.
kind	string	no	—	Optional filter: "type", "func", "macro", "const", or "trait".

Result

{
  "count": 3,
  "total_indexed": 142,
  "results": [
    {
      "id": "std.core.ArrayList.append",
      "package": "std.core",
      "type": "ArrayList",
      "member": "append",
      "kind": "func",
      "signature": "func append(value: T): Unit",
      "summary": "Appends `value` to the end of the list. Amortised O(1).",
      "detail": "If the underlying buffer is full, the list grows by 1.5x or 2x. Pre-allocate with `ArrayList<T>(capacity: n)` if you know the size in advance."
    }
  ]
}

cangjie_doc

Look up the long-form record for a single API entry, with a few related entries from the same package.

Input

Field	Type	Required	Default	Description
package	string	yes	—	Package name, e.g. "std.collection".
type	string	no	—	Type name within the package. Omit for free functions.
member	string	no	—	Member name within the type. Omit for the type itself.
related	integer	no	5	How many related entries to include. Hard cap 20.

Result (found)

{
  "found": true,
  "id": "std.core.ArrayList.append",
  "package": "std.core",
  "type": "ArrayList",
  "member": "append",
  "kind": "func",
  "signature": "func append(value: T): Unit",
  "summary": "Appends `value` to the end of the list. Amortised O(1).",
  "detail": "If the underlying buffer is full, the list grows by 1.5x or 2x. Pre-allocate with `ArrayList<T>(capacity: n)` if you know the size in advance.",
  "related": [
    { "id": "std.core.ArrayList.size", "signature": "func size(): Int64", "summary": "..." }
  ]
}

Result (not found)

When the requested entry does not exist, the tool returns {"found": false, "requested": "...", "alternatives": [...]} with a small fuzzy-search fallback so the LLM can recover from a typo.

cangjie_patterns

Search the built-in pattern library for short, idiomatic Cangjie snippets.

Input

Field	Type	Required	Default	Description
query	string	yes	—	Free-text intent. Examples: "parse json", "spawn task", "test runner".
limit	integer	no	5	Max results. Hard cap 10.

Result

{
  "count": 2,
  "total_indexed": 10,
  "results": [
    {
      "id": "json-parse",
      "title": "Parse a JSON document",
      "tags": ["json", "parse", "decoder"],
      "body": "import std.json.JsonParser\nlet v = match (JsonParser(text).parse()) {\n  case Ok(x)  => x\n  case Err(e) => throw Exception(\"bad json: ${e}\")\n}\n",
      "notes": "Use cjdrift's parseStrict (in core.jsonx) to reject trailing garbage."
    }
  ]
}

cangjie_run

Run an allow-listed cjpm or cjpm / cjc / cjlint / cjfmt subcommand and return the captured output.

Input

Field	Type	Required	Default	Description
command	string	yes	—	One of: build, test, run, update, clean, lint, fmt, check, info, version.
cwd	string	no	"."	Working directory.
extra_args	array	no	[]	Optional extra flags passed to the subcommand verbatim.
timeout_ms	integer	no	60000	Process timeout. Hard cap 600000.

Result

{
  "binary": "cjpm",
  "args": ["build"],
  "cwd": ".",
  "exit_code": 0,
  "elapsed_ms": 1234,
  "output": "... stdout + stderr, truncated to 16 KiB ...",
  "ok": true
}

cangjie_lint

Run cjlint and group the findings by rule and severity.

Input

Field	Type	Required	Default	Description
path	string	no	"."	Source directory to lint.
rules	array	no	[]	Optional list of rule IDs (e.g. ["G.FMT.01"]).
severity	string	no	"info"	One of "error", "warning", "info". Filters out lower severities.

Result

{
  "total_diagnostics": 47,
  "kept_after_severity_filter": 12,
  "severity_filter": "warning",
  "by_rule": [
    { "rule": "G.FMT.01", "count": 7 },
    { "rule": "G.ENU.01", "count": 5 }
  ],
  "findings": [
    {
      "rule": "G.FMT.01",
      "level": "warning",
      "message": "...",
      "file": "src/foo.cj",
      "line": 12,
      "column": 5
    }
  ]
}

cangjie_fmt

Run cjfmt in either dry_run (default) or write mode.

Input

Field	Type	Required	Default	Description
path	string	yes	—	Path to a `.cj` file or a directory.
dry_run	boolean	no	true	If true, do not write; just return a unified diff.
config	string	no	—	Optional cjfmt config file path.

Result

{
  "exit_code": 0,
  "mode": "dry_run",
  "diff": "--- src/foo.cj\n+++ src/foo.cj\n@@ ...",
  "changed": true
}

cangjie_pkg_search

Search the Cangjie central registry for packages.

Input

Field	Type	Required	Default	Description
query	string	yes	—	Search term. Matches against package name and description.
limit	integer	no	10	Max results. Hard cap 20.

Result

{
  "count": 3,
  "query": "json",
  "results": [
    {
      "name": "fast_json_cj",
      "description": "High-performance JSON serialization library",
      "latest_version": "1.0.4",
      "downloads_month": 0
    }
  ]
}

When the registry is unreachable, the source field on each result is set to "offline-seed".

cangjie_scaffold

Generate a ready-to-build Cangjie project skeleton.

Input

Field	Type	Required	Default	Description
path	string	yes	—	Directory to create the project in.
name	string	no	dir basename	Project name.
kind	string	no	"executable"	One of "executable", "library", "mcp-server".
force	boolean	no	false	Overwrite existing files.

Result

{
  "path": "/path/to/project",
  "kind": "executable",
  "name": "myapp",
  "written": ["cjpm.toml", "src/main.cj", "README.md"]
}

cangjie_explain

Look up a Cangjie / cjc / cjpm / cjlint error message and return one or more hypothesised diagnoses.

Input

Field	Type	Required	Description
error	string	yes	Raw error text. May be multi-line.

Result

{
  "matches": 1,
  "rule_count": 14,
  "diagnoses": [
    {
      "title": "Cannot find symbol",
      "category": "import",
      "body": "The compiler does not see a name you used.  The most common causes are ...",
      "fixes": [
        "Add `import <package>` at the top of the file",
        "Check spelling; Cangjie identifiers are case-sensitive",
        "Run `cjpm update` to pull missing dependencies"
      ]
    }
  ]
}

cangjie_read_file

Read a text file under a configured project root.

Input

Field	Type	Required	Default	Description
path	string	yes	—	File path, relative to `root`.
root	string	no	"."	Project root.
start_line	integer	no	0	0-based inclusive start line.
end_line	integer	no	-1	0-based exclusive end line. -1 = end of file.
max_bytes	integer	no	65536	Hard cap on returned bytes. Hard cap 1 MiB.
allow_absolute	boolean	no	false	Permit absolute paths.

Result

{
  "path": "/abs/path/to/file.cj",
  "total_lines": 240,
  "start_line": 10,
  "end_line": 25,
  "bytes_returned": 1024,
  "content": "..."
}

cangjie_write_file

Write a text file under a configured project root. Requires confirm: true to actually perform the write.

Input

Field	Type	Required	Default	Description
path	string	yes	—	File path, relative to `root`.
content	string	yes	—	New file content.
root	string	no	"."	Project root.
confirm	boolean	no	false	Must be true to actually write.
allow_absolute	boolean	no	false	Permit absolute paths.

Result (preview, confirm not set)

{
  "status": "preview",
  "hint": "set confirm=true to actually write the file",
  "would_write_bytes": 1024,
  "path": "src/foo.cj"
}

Result (written)

{
  "status": "written",
  "path": "/abs/path/to/foo.cj",
  "bytes": 1024
}

cangjie_list_dir

List the entries of a directory under the project root.

Input

Field	Type	Required	Default	Description
path	string	no	"."	Directory path, relative to `root`.
root	string	no	"."	Project root.
include_hidden	boolean	no	true	Include dotfiles.
allow_absolute	boolean	no	false	Permit absolute paths.

Result

{
  "path": "/abs/path/to/dir",
  "count": 5,
  "entries": [
    { "name": "src", "type": "dir", "size": 0 },
    { "name": "cjpm.toml", "type": "file", "size": 312 }
  ]
}

FilesExpand file tree

tools.md

Latest commit

History

tools.md

File metadata and controls

Tool reference

cangjie_apis

Input

Result

cangjie_doc

Input

Result (found)

Result (not found)

cangjie_patterns

Input

Result

cangjie_run

Input

Result

cangjie_lint

Input

Result

cangjie_fmt

Input

Result

cangjie_pkg_search

Input

Result

cangjie_scaffold

Input

Result

cangjie_explain

Input

Result

cangjie_read_file

Input

Result

cangjie_write_file

Input

Result (preview, confirm not set)

Result (written)

cangjie_list_dir

Input

Result