OXC AST MCP Server Development

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.

Project Overview

This MCP server provides three main tools:

Initial Setup

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

```

Build Commands

Development Build

```sh

cargo build

```

Release Build

```sh

cargo build --release

```

Testing

Run All Tests

```sh

cargo test

```

Run Specific Test

```sh

cargo test test_name

```

Run Tests in Specific Module

```sh

cargo test docs::tests

```

Architecture

Project Structure

Tool Implementation Pattern

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.

OXC Integration

The tools use these OXC crates:

Supported file extensions: `js`, `mjs`, `cjs`, `jsx`, `ts`, `mts`, `cts`, `tsx`

Adding a New Tool

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

```

Updating OXC Dependencies

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

```

AST Documentation Generation

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!`.

Error Handling

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.

Development Workflow

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)

Important Notes