Development guidance for building and extending the OXC AST MCP server - a Model Context Protocol server exposing OXC parser functionality for JavaScript/TypeScript code analysis
Development guidance for working with the OXC AST MCP server - a Model Context Protocol server that exposes OXC parser functionality for parsing and analyzing JavaScript/TypeScript code.
This MCP server provides three main tools:
1. Before building for the first time, generate the AST node documentation:
```sh
node generate-oxc_ast-nodes.mjs > ast-nodes.generated.json
```
Note: This requires nightly Rust toolchain for unstable rustdoc JSON output features.
2. Build the project:
```sh
cargo build
```
```sh
cargo build
```
```sh
cargo build --release
```
```sh
cargo test
```
```sh
cargo test test_name
```
```sh
cargo test docs::tests
```
Each tool follows this pattern:
1. Decorated with `#[mcp_tool(...)]` macro containing metadata (name, title, description)
2. Implements `MyTool` trait with a `call()` method
3. Returns `Result<CallToolResult, CallToolError>`
4. Uses OXC libraries for parsing/validation
The `tool_box!` macro in `src/tools/mod.rs` combines all tools into a `MyTools` enum that handles dispatch.
The tools use these OXC crates:
Supported file extensions: `js`, `mjs`, `cjs`, `jsx`, `ts`, `mts`, `cts`, `tsx`
1. Create a new file in `src/tools/` (e.g., `src/tools/my_tool.rs`)
2. Define a struct with the `#[mcp_tool(...)]` attribute:
```rust
#[mcp_tool(
name = "my_tool",
title = "My Tool",
description = "Description of what this tool does"
)]
pub struct MyNewTool {
// Tool parameters as struct fields
}
```
3. Implement the `MyTool` trait:
```rust
impl MyTool for MyNewTool {
fn call(&self) -> Result<CallToolResult, CallToolError> {
// Tool implementation
}
}
```
4. Import the tool in `src/tools/mod.rs`:
```rust
mod my_tool;
pub use my_tool::MyNewTool;
```
5. Add the tool to the `tool_box!` macro in `src/tools/mod.rs`:
```rust
tool_box!(MyTools { ParseTool, CheckTool, DocsTool, MyNewTool });
```
6. Test your new tool:
```sh
cargo test
```
When updating OXC dependencies in `Cargo.toml`:
1. Update all `oxc_*` crates to the same version:
```toml
[dependencies]
oxc_allocator = "x.y.z"
oxc_parser = "x.y.z"
oxc_semantic = "x.y.z"
oxc_span = "x.y.z"
```
2. Regenerate AST documentation:
```sh
node generate-oxc_ast-nodes.mjs > ast-nodes.generated.json
```
3. Test all tools to ensure compatibility:
```sh
cargo test
```
The `generate-oxc_ast-nodes.mjs` script:
1. Runs `cargo rustdoc` with JSON output to extract type information
2. Parses the generated JSON documentation
3. Extracts all public structs and enums from `oxc_ast`
4. Filters out internal types (AstBuilder, AstKind, etc.)
5. Generates simplified Rust-style definitions with field types and docs
6. Outputs to `ast-nodes.generated.json`
This JSON file is embedded into the `docs` tool at compile time using `include_str!`.
The project uses a custom `StringError` type in `src/tools/mod.rs` that provides simple string-based error messages. These convert to `CallToolError` for MCP responses.
1. Make code changes to tool implementations or add new tools
2. Run tests to verify functionality: `cargo test`
3. Build the project: `cargo build`
4. If AST node structures changed, regenerate documentation: `node generate-oxc_ast-nodes.mjs > ast-nodes.generated.json`
5. Test the MCP server with a compatible client (e.g., Claude Code)
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/oxc-ast-mcp-development/raw