input-source-help.ts•4.09 kB
/**
* Provides help and instructions for input source variable errors.
* This tool can be called when there are issues with inputVariableSource parameters.
*/
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
/**
* Returns detailed instructions for handling input source variable errors.
* @returns Comprehensive help text for troubleshooting input source variables.
*/
function getToolUsageHelpInstructions(): string {
return `
# Input Source Mapping Guide
The **\`inputVariableSource\`** object specifies the origin of each input field in an API call.
It ensures transparency about where every value in the request body comes from.
---
## Structure
The structure of **\`inputVariableSource\`** must **exactly mirror** the request body.
Each field in the body must have a corresponding entry with its source type.
\`\`\`json
{
"inputVariableSource": {
"body": {
"field_name": "source_type",
"nested_object": {
"nested_field": "source_type"
}
}
}
}
\`\`\`
---
## Valid Source Types
- **"user_input"** — Value directly provided by the user
- **"generated_by_model"** — Value automatically generated by the model
- **"inferred_from_context"** — Value derived from previous context or data
---
## Common Errors & Fixes
| Issue | Example | Fix |
|-------|----------|-----|
| **Missing mapping** | \`inputVariableSource\` absent | Add the full mapping structure |
| **Incomplete mapping** | Some fields missing | Map every field in the body |
| **Invalid source type** | Unknown label used | Use only the 3 valid types |
| **Structure mismatch** | Structure differs from body | Ensure identical nesting |
---
## Example
\`\`\`json
{
"body": {
"order_id": "ORDER_123",
"amount": 1000,
"currency": "INR",
"customer_details": {
"customer_name": "John Doe",
"customer_email": "john@example.com"
}
},
"inputVariableSource": {
"body": {
"order_id": "user_input",
"amount": "user_input",
"currency": "generated_by_model",
"customer_details": {
"customer_name": "user_input",
"customer_email": "user_input"
}
}
}
}
\`\`\`
---
## Best Practices
1. **Always include \`inputVariableSource\`** — It is mandatory.
2. **Mirror body structure** — Nested keys must align exactly.
3. **Use correct types** — Only the three valid source types are accepted.
4. **Handle arrays carefully** — Map the array field as a whole, not its elements.
5. **Validate before sending** — Run a JSON structure check if in doubt.
---
## Troubleshooting
- **Validation failed:** Missing or mismatched fields → recheck structure
- **Unexpected type:** Ensure all values are valid source strings
- **Mapping missing:** Verify every body field has a mapped source
- **Nested mismatch:** Align nested objects one-to-one with request body
If issues persist, refer to the API endpoint documentation for any field-specific requirements.
`;
}
/**
* Registers the "get-input-source-help" tool to the MCP server.
* This tool provides comprehensive instructions for handling input source variable errors.
* @param server - The MCP server instance.
*/
export async function createCFContextInitializerTool(server: McpServer): Promise<void> {
server.tool(
"cashfree_context_initializer",
"This is the FIRST tool that must be called before using ANY other Cashfree MCP tool or generating Cashfree-related outputs. It initializes full context for the Cashfree ecosystem — including schemas, APIs, plugin behaviors, transformation logic, and usage conventions. Always invoke this tool before any reasoning, generation, or validation, so the model can load complete domain knowledge and ensure consistent, accurate responses across all Cashfree tools.",
{} as const,
async () => {
const instructions = getToolUsageHelpInstructions();
return {
content: [
{
type: "text" as const,
text: instructions,
},
],
};
}
);
}