create-mcp-tool— agent skill

Purpose

Use this skill when creating a new MCP tool in the CodeScene MCP Server project. It encodes the exact conventions, patterns, and file structure that all existing tools follow.

Project Context

• Framework: rmcp (Rust MCP SDK) with #[tool(tool_box)] macros
• Language: Rust
• Source root: src/
• Server entry point: src/main.rs (contains CodeSceneServer struct and tool method bindings)
• Tools directory: src/tools/ with mod.rs for module declarations and parameter type definitions
• Dependency injection: Via the CodeSceneServer struct, which holds cli_runner: Arc<dyn CliRunner> and http_client: Arc<dyn HttpClient> trait objects

Step-by-Step

1. Create the tool file

Create a new .rs file in src/tools/ named after the tool using snake_case:

src/tools/<tool_name>.rs

2. Define the parameter struct (if needed)

If the tool needs parameters beyond what already exists, add a new struct to src/tools/mod.rs:

/// Parameters for <description of what the tool does>.
#[derive(Debug, Deserialize, schemars::JsonSchema)]
pub struct MyToolParam {
    /// Description of this field for the JSON Schema (visible to LLM clients).
    pub some_field: String,

    /// Optional fields use Option<T> with #[serde(default)].
    #[serde(default)]
    pub optional_field: Option<String>,
}

Existing parameter structs that may already fit your tool:

Reuse an existing struct when possible. Only define a new one if no existing struct matches.

3. Add the module declaration

Add a pub mod line in src/tools/mod.rs, keeping the list alphabetically sorted:

pub mod my_tool;

4. Implement the tool handler

Create src/tools/<tool_name>.rs with a handle function:

use std::path::Path;

use rmcp::model::{CallToolResult, Content};
use rmcp::ErrorData;

use crate::docker;
use crate::event_properties;
use crate::tools::common::{run_review, tool_error};
use crate::tools::FilePathParam;
use crate::CodeSceneServer;

pub(crate) async fn handle(
    server: &CodeSceneServer,
    params: FilePathParam,
) -> Result<CallToolResult, ErrorData> {
    // 1. Check for access token
    if let Some(r) = server.require_token() {
        return Ok(r);
    }

    // 2. Trigger background version check
    server.version_checker.check_in_background();

    // 3. Adapt paths for Docker if needed
    let file_path = docker::adapt_path_for_docker(Path::new(&params.file_path));

    // 4. Call the CLI or HTTP client via the server's injected dependencies
    let result = run_review(Path::new(&file_path), &*server.cli_runner).await;

    // 5. Handle the result
    match result {
        Ok(output) => {
            // Track success event
            let props = event_properties::score_properties(Path::new(&params.file_path), None);
            server.track("my-tool", props);

            // Format and return
            let text = server.maybe_version_warning(&output).await;
            Ok(CallToolResult::success(vec![Content::text(text)]))
        }
        Err(e) => {
            server.track_err("my-tool", &e.to_string());
            Ok(tool_error(&format!("Error: {e}")))
        }
    }
}

Key conventions:

• The handler is a free `async fn`, not a method on a struct. It receives &CodeSceneServer and the parameter struct.
• Always check for the access token first with server.require_token().
• Always trigger the background version check with server.version_checker.check_in_background().
• Use `docker::adapt_path_for_docker()` when the tool receives file paths from the client.
• Track events with server.track() on success and server.track_err() on failure.
• Use `server.maybe_version_warning()` to prepend version update notices to the response.
• Return `tool_error()` from crate::tools::common for error results (sets is_error = true).
• Return type is always `Result<CallToolResult, ErrorData>`.

Choose the right dependency based on what the tool does:

5. Wire the tool method on CodeSceneServer

In src/main.rs, inside the #[tool_router] impl CodeSceneServer block, add a new method:

#[tool(
    description = "One-line summary of what this tool does.\nAdditional detail on inputs, outputs, and how the LLM should present results.",
    input_schema = inlined_schema_for::<MyToolParam>()
)]
async fn my_tool(
    &self,
    Parameters(params): Parameters<MyToolParam>,
) -> Result<CallToolResult, ErrorData> {
    tools::my_tool::handle(self, params).await
}

Conventions:

• The `description` string is critical — it becomes the tool description visible to LLM clients. Be specific about inputs, outputs, and how the LLM should present results.
• The method name becomes the MCP tool name as seen by clients.
• Use `inlined_schema_for::<ParamType>()` to generate the JSON Schema for the parameter struct.
• The method body is a one-liner that delegates to the handler in src/tools/<tool_name>.rs.
• For tools with no parameters, omit input_schema and Parameters:

  #[tool(description = "...")]
  async fn my_tool(&self) -> Result<CallToolResult, ErrorData> {
      tools::my_tool::handle(self).await
  }

Also add the parameter struct to the import at the top of src/main.rs if you defined a new one:

use crate::tools::{
    ChangeSetParam, FilePathParam, GetConfigParam, GitRepoParam, MyToolParam,
    OptionalContext, OwnershipParam, ProjectFileParam, ProjectParam,
    RefactorParam, SetConfigParam,
};

6. Write inline tests

Add a #[cfg(test)] module at the bottom of src/tools/<tool_name>.rs:

#[cfg(test)]
mod tests {
    use rmcp::handler::server::wrapper::Parameters;

    use crate::tests::{
        assert_error_contains, assert_success_contains, assert_token_error, clear_token,
        make_cli_mock_server, make_server, set_token, MockCliRunner,
    };
    use crate::tools::FilePathParam;

    #[tokio::test]
    async fn rejects_missing_token() {
        let _g = clear_token();
        let params = FilePathParam {
            file_path: "/tmp/f.rs".to_string(),
        };
        let result = make_server(false)
            .my_tool(Parameters(params))
            .await
            .unwrap();
        assert_token_error(&result);
    }

    #[tokio::test]
    async fn success_returns_expected_content() {
        let _g = set_token("tok");
        let server = make_cli_mock_server(MockCliRunner::with_ok(r#"{"score":8.5,"review":[]}"#));
        let params = FilePathParam {
            file_path: "/tmp/test.rs".to_string(),
        };
        let result = server.my_tool(Parameters(params)).await.unwrap();
        assert_success_contains(&result, "expected content");
    }

    #[tokio::test]
    async fn error_returns_tool_error() {
        let _g = set_token("tok");
        let server = make_cli_mock_server(MockCliRunner::with_err(1, "tool failed"));
        let params = FilePathParam {
            file_path: "/tmp/test.rs".to_string(),
        };
        let result = server.my_tool(Parameters(params)).await.unwrap();
        assert_error_contains(&result, "tool failed");
    }
}

Key patterns:

• Use `set_token()` / `clear_token()` — these acquire a mutex guard (TokenGuard) that serializes tests touching CS_ACCESS_TOKEN. Always bind the guard to _g so it lives for the test's duration.
• Use `MockCliRunner` to inject controlled CLI responses:
• MockCliRunner::with_ok(output) — simulates successful CLI execution
• MockCliRunner::with_err(code, stderr) — simulates CLI failure
• MockCliRunner::with_responses(vec![...]) — queues multiple responses for tools that make multiple CLI calls
• Use `make_cli_mock_server()` to create a CodeSceneServer with mocked CLI and default HTTP.
• Use `make_server_with_mocks()` when you need to mock both CLI and HTTP.
• Call the tool method directly on the server instance: server.my_tool(Parameters(params)).
• Use assertion helpers: assert_success_contains, assert_error_contains, assert_token_error, assert_standalone_error.
• Test at minimum: missing token rejection, success path, and error path.

7. Validate Code Health and fix any issues

After the tool is implemented, tested, and registered, run the CodeScene Code Health tools to ensure the new code meets quality standards. Do not consider the tool complete until Code Health passes without regressions.

Choose the appropriate scope:

Recommended workflow:

1. Run code_health_review on each new/modified file (at minimum src/tools/<tool_name>.rs).
2. If any code smells or regressions are reported:

• Refactor the flagged code to resolve the issues.
• Re-run code_health_review after each fix to confirm improvement.

1. Before committing, run pre_commit_code_health_safeguard to catch anything across all changed files.
2. Before opening a PR, run analyze_change_set against the target branch to ensure no regressions across the full change set.

Target: Code Health 10.0. Scores of 9+ are not "good enough" — aim for optimal.

Canonical Example: code_health_score

The simplest existing tool to reference is src/tools/code_health_score.rs. It demonstrates:

• Single parameter (FilePathParam)
• Free async fn handle() receiving &CodeSceneServer and params
• Token check, version check, Docker path adaptation
• CLI call via server.cli_runner
• Event tracking on success and error
• Version warning prepended to output
• Inline #[cfg(test)] module with mocked dependencies

Refer to src/tools/code_health_score.rs as the minimal template.

Checklist

Before considering the tool complete:

• [ ] Tool file created at src/tools/<tool_name>.rs
• [ ] Parameter struct defined in src/tools/mod.rs (or existing struct reused)
• [ ] Module declared in src/tools/mod.rs (pub mod <tool_name>;)
• [ ] Handler function pub(crate) async fn handle() implemented with token check, version check, and error handling
• [ ] Tool method added to #[tool_router] impl CodeSceneServer in src/main.rs with #[tool(description = "...")]
• [ ] Parameter struct imported in src/main.rs (if new)
• [ ] Inline tests cover: missing token, success path, and error path
• [ ] Tests use MockCliRunner / MockHttpClient for dependency injection
• [ ] Run tests with cargo test
• [ ] code_health_review passes on all new/modified files with no code smells
• [ ] pre_commit_code_health_safeguard reports no regressions before commit
• [ ] analyze_change_set reports no regressions before opening a PR