razorpay-mcp-server / rules

---
description: 
globs: 
alwaysApply: true
---

# Razorpay Tool Generator

This rule generates tool implementations for the Razorpay MCP server based on API documentation.

## Required Format

This rule requires:

1. A Razorpay API documentation URL starting with `https://razorpay.com/docs/api/`
2. The SDK function signature that the tool will call

Example of valid invocation:
```
@new-tool-from-docs.mdc DOC_LINK: @https://razorpay.com/docs/api/payment-links/create-standard/
SDK_FUNCTION:
func (pl *PaymentLink) Create(data map[string]interface{}, extraHeaders map[string]string) (map[string]interface{}, error) {
    url := fmt.Sprintf("/%s%s", constants.VERSION_V1, constants.PaymentLink_URL)
    return pl.Request.Post(url, data, extraHeaders)
}
```

IMPORTANT: If the DOC_LINK or SDK_FUNCTION are missing or in an incorrect format, REFUSE to proceed further.

## Implementation Checklist

This checklist **MUST** be included in the final response to verify all implementation steps are complete.
IMPORTANT: Include this unchecked checklist at the END of the implementation, NOT at the beginning.

- [ ] Implement tool function based on API docs
- [ ] Register tool in tools.go
- [ ] Create unit tests with full coverage (positive case, all negative cases, edge cases)
- [ ] Update the "Available Tools" section in the main README.md. Make sure the new additions are correctly formatted.
- [ ] Double check that we are not repeating any of the Common Issues mentioned below.
- [ ] Run linter and fix errors if any (REQUIRED)
- [ ] Run tests and fix errors if any (REQUIRED)

COMPLETION CRITERIA:
1. The task is considered accomplished only if the checklist and summary are posted.
2. Once the task is completed you should stop and give control to the user. You SHOULD NOT infer additional tools to implement.

## ⚠️ IMMEDIATE ACTION REQUIRED ⚠️

Upon receiving this rule invocation:

1. **DO NOT** ask for user input or confirmation before implementing code
2. **DO** use the `edit_file` tool to create/modify the following files:
   - Primary implementation: `pkg/razorpay/{resource_type}.go`
   - Test implementation: `pkg/razorpay/{resource_type}_test.go`
   - Update toolset registration: `pkg/razorpay/tools.go`
   - Update the README.md

## Implementation

Before the implementation use the documentation URL provided to figure out the request contract, required parameters, descriptions of the parameters, and the response contract.

Now follow the detailed implementation guide in [pkg/razorpay/README.md](mdc:../pkg/razorpay/README.md) for creating tools and start making code changes.

Other guidelines:
1. [Razorpay Go SDK Constants](mdc:https:/github.com/razorpay/razorpay-go/blob/master/constants/url.go) - Use these constants for specifying the api endpoints while writing the tests.
2. Use the payload and response from the docs provided to write the positive test case for the tool.

STYLE:
Look at the linters and linter settings in the .golangci.yaml file and make sure to follow the same style while coding.

IMPORTANT: You **MUST** ALWAYS go through the Post Implementation steps once the code changes are done.

## Implementation References

For detailed code patterns and examples, refer to the following sections in the [pkg/razorpay/README.md](mdc:../pkg/razorpay/README.md):

- **Tool Structure**: See the "Tool Structure" section for the function template
- **Parameter Definition**: See the "Parameter Definition" section for defining parameters
- **Parameter Validation**: See the "Parameter Validation" section for validation examples
- **Example GET/POST Endpoints**: See the example sections for complete implementation patterns
- **Unit Testing**: See the "Writing Unit Tests" section for test patterns and best practices

## ⚠️ Common Issues & Troubleshooting ⚠️

### 1. Query Parameters in Mock Tests

The `mock.Endpoint` struct does NOT have a queryParams field:

```go
type Endpoint struct {
    Path     string
    Method   string
    Response interface{}
}
```

### 1. Query Parameter Limitations in Mock Tests

The mock server doesn't validate query parameters. When testing endpoints with query parameters:

```go
// DOESN'T WORK - Gorilla Mux treats this as a literal path ❌
mock.Endpoint{
    Path:     apiPath + "?count=2&from=123&skip=1",
    Method:   "GET",
    Response: successResponse,
}

// WORKS - Use only the base path ✅
mock.Endpoint{
    Path:     apiPath,  // Only the base path without query parameters
    Method:   "GET",
    Response: successResponse,
}
```

### 2. Line Length Linter Errors

When encountering line length errors ("The line is X characters long, which exceeds the maximum of Y characters"):

1. Option 1: Add `//nolint:lll` comment at the end of the line:
```go
return mcpgo.NewTool(
    "tool_name",
    "This is a very long description that exceeds the line length limit", //nolint:lll
    parameters,
    handler,
)
```

2. Option 2: Break the string into multiple concatenated lines:
```go
return mcpgo.NewTool(
    "tool_name",
    "This is a very long description " +
        "that exceeds the line length limit",
    parameters,
    handler,
)
```

3. Option 3: For comments, split into multiple comment lines:
```go
// This is a very long comment that would exceed the line length limit
// so it's split into multiple lines.
func ToolName() {}
```

### 3. Missing Steps in the Implementation Checklist

IMPORTANT: The Implementation Checklist MUST be complete before submitting. Pay particular attention to these required steps:

- [ ] Run linter and fix errors if any (REQUIRED)
- [ ] Run tests and fix errors if any (REQUIRED)

If any checklist items remain unchecked, complete them before proceeding. The implementation is considered incomplete until all required steps are addressed.

## Test Coverage Requirements

Your tests MUST include:
- Positive test case with all parameters
- Negative test case for EACH required parameter
- Negative test case for multiple validation failures (e.g., wrong types)
- Any edge cases specific to this tool

## ⚠️ Required Verification Steps ⚠️

After implementing code changes, ALWAYS perform these verification steps:

1. You **MUST** run the linter to ensure code quality:
  ```
  run_terminal_cmd golangci-lint run
  ```
  Fix any issues reported by the linter. Try at least two iterations of fixes for the errors before giving up.

2. You **MUST** run tests to verify functionality:
  ```
  run_terminal_cmd go test ./...
  ```
  Ensure all tests pass. If any tests fail, investigate the failures and fix the issues. Try at least two iterations of fixes for the errors before giving up.

## Key Packages and Functionality

Use this section as a reference for the key packages incase you get lost.

### `pkg/razorpay` - Main Implementation Package

**Path:** `pkg/razorpay/`

Contains all Razorpay API tool implementations, including:
- Tool function definitions (by resource type)
- Parameter validation functions
- Request/response handling

### `pkg/razorpay/tools_params.go` - Fluent Validator

**Path:** `pkg/razorpay/tools_params.go`

Contains the fluent validator implementation for parameter validation:
- `Validator` - Type that provides a fluent interface for validation
- `NewValidator` - Creates a new validator for a request
- `HasErrors` - Checks if validation errors exist
- `HandleErrorsIfAny` - Formats all errors into a tool result
- `ValidateAndAddRequiredString` - Validates required string parameters
- `ValidateAndAddOptionalString` - Validates optional string parameters
- `ValidateAndAddRequiredInt` - Validates required integer parameters
- `ValidateAndAddOptionalInt` - Validates optional integer parameters
- `ValidateAndAddRequiredFloat` - Validates required float parameters
- `ValidateAndAddOptionalFloat` - Validates optional float parameters
- `ValidateAndAddRequiredBool` - Validates required boolean parameters
- `ValidateAndAddOptionalBool` - Validates optional boolean parameters
- `ValidateAndAddRequiredMap` - Validates required map parameters
- `ValidateAndAddOptionalMap` - Validates optional map parameters
- `ValidateAndAddRequiredArray` - Validates required array parameters
- `ValidateAndAddOptionalArray` - Validates optional array parameters
- `ValidateAndAddPagination` - Validates and adds pagination parameters
- `ValidateAndAddExpand` - Validates and adds expand parameters

### `pkg/razorpay/test_helpers.go` - Testing Utilities

**Path:** `pkg/razorpay/test_helpers.go`

Contains testing utilities used for unit tests:
- `RazorpayToolTestCase` - Test case structure
- `runToolTest` - Test execution function
- Mock client setup functions

### `pkg/razorpay/tools.go` - Tool Registration

**Path:** `pkg/razorpay/tools.go`

Contains the toolset registration system:
- `NewToolSets` function
- Toolset definitions and organization
- Tool grouping by resource type

### `pkg/razorpay/mock` - HTTP Mocking

**Path:** `pkg/razorpay/mock/`

Contains HTTP mocking utilities for testing:
- `NewHTTPClient` - Creates mock HTTP clients
- `Endpoint` - Mock endpoint definition

### `pkg/mcpgo` - MCP Protocol Package

**Path:** `pkg/mcpgo/`

Contains the Model Context Protocol implementation:
- `Tool` interface definition
- `ToolParameter` types
- Response handling utilities (`NewToolResultJSON`, etc.)

### `github.com/razorpay/razorpay-go` - Razorpay Go SDK

**Imported as:** `rzpsdk "github.com/razorpay/razorpay-go"`

Official Razorpay client library providing:
- `Client` struct with resource-specific clients (Payment, Order, PaymentLink, etc.)
- API methods that map to Razorpay REST endpoints
- Constants for API URLs (`constants` package)
- Request/response handling