stacksfinder-mcp

Instructions

Implementation Reference

• src/tools/api-keys.ts:41-123 (handler)

  The executeSetupApiKey function handles the tool execution: authenticates with StacksFinder API using email/password, creates a new API key, handles errors with specific messages, and returns formatted instructions including the key and setup commands.

  export async function executeSetupApiKey(
  	input: SetupApiKeyInput
  ): Promise<{ text: string; isError?: boolean; apiKey?: string }> {
  	const config = getConfig();
  	const { email, password, keyName } = input;
  
  	debug('Setting up API key for', email);
  
  	try {
  		const response = await fetch(`${config.apiUrl}/api/v1/mcp/setup`, {
  			method: 'POST',
  			headers: {
  				'Content-Type': 'application/json'
  			},
  			body: JSON.stringify({
  				email,
  				password,
  				keyName: keyName || 'MCP Auto-generated'
  			})
  		});
  
  		const data = (await response.json()) as SetupApiResponse;
  
  		if (!response.ok || !data.success) {
  			let errorMessage = data.message || data.error || 'Failed to create API key';
  
  			// Add helpful context for common errors
  			if (data.error === 'TIER_REQUIRED') {
  				errorMessage = `Pro or Team tier required. Upgrade at ${config.apiUrl}/pricing`;
  			} else if (data.error === 'LIMIT_EXCEEDED') {
  				errorMessage = `API key limit reached. Manage keys at ${config.apiUrl}/account/developer/api-keys`;
  			} else if (data.error === 'INVALID_CREDENTIALS') {
  				errorMessage = 'Invalid email or password. Please check your credentials.';
  			}
  
  			return {
  				text: `**Error**: ${errorMessage}`,
  				isError: true
  			};
  		}
  
  		info('API key created successfully');
  
  		// Return the key with instructions
  		const text = `## API Key Created Successfully
  
  **Key**: \`${data.apiKey}\`
  **Key ID**: ${data.keyId}
  **Prefix**: ${data.prefix}
  
  **IMPORTANT**: Save this key now - it cannot be retrieved again!
  
  ### Configure in Claude Code
  
  Run this command to add the key:
  
  \`\`\`bash
  claude mcp add-json stacksfinder '{"command": "npx", "args": ["-y", "@stacksfinder/mcp-server"], "env": {"STACKSFINDER_API_KEY": "${data.apiKey}"}}'
  \`\`\`
  
  Or set the environment variable:
  
  \`\`\`bash
  export STACKSFINDER_API_KEY="${data.apiKey}"
  \`\`\`
  
  ### Manage Your Keys
  
  View and manage keys at: ${config.apiUrl}/account/developer/api-keys`;
  
  		return { text, apiKey: data.apiKey };
  	} catch (err) {
  		if (err instanceof McpError) {
  			return { text: err.toResponseText(), isError: true };
  		}
  
  		const errorMessage = err instanceof Error ? err.message : 'Failed to setup API key';
  		return {
  			text: `**Error**: ${errorMessage}\n\nMake sure you can reach ${config.apiUrl}`,
  			isError: true
  		};
  	}
  }

• src/tools/api-keys.ts:6-13 (schema)

  Zod schema defining the input parameters for the setup_api_key tool: email (required, validated as email), password (required, non-empty), keyName (optional, max 100 chars).

  /**
   * Input schema for setup_api_key tool.
   */
  export const SetupApiKeyInputSchema = z.object({
  	email: z.string().email().describe('Your StacksFinder account email'),
  	password: z.string().min(1).describe('Your StacksFinder account password'),
  	keyName: z.string().max(100).optional().describe('Optional name for the API key')
  });

• src/server.ts:302-328 (registration)

  Registers the 'setup_api_key' tool on the MCP server using server.registerTool, providing title, description from toolDefinition, inputSchema (mirroring the Zod schema), annotations, and an async handler that parses input with SetupApiKeyInputSchema and calls executeSetupApiKey.

  // Register setup_api_key tool (API-based, no auth required)
  server.registerTool(
  	setupApiKeyToolDefinition.name,
  	{
  		title: 'Setup API Key',
  		description: setupApiKeyToolDefinition.description,
  		inputSchema: {
  			email: z.string().email().describe('Your StacksFinder account email'),
  			password: z.string().min(1).describe('Your StacksFinder account password'),
  			keyName: z.string().max(100).optional().describe('Optional name for the API key')
  		},
  		annotations: {
  			readOnlyHint: false,
  			destructiveHint: false,
  			openWorldHint: false
  		}
  	},
  	async (args) => {
  		debug('setup_api_key called', args.email);
  		const input = SetupApiKeyInputSchema.parse(args);
  		const { text, isError } = await executeSetupApiKey(input);
  		return {
  			content: [{ type: 'text', text }],
  			isError
  		};
  	}
  );

• src/tools/api-keys.ts:17-24 (schema)

  Tool metadata definition including the exact name 'setup_api_key' and detailed description used during registration.

  /**
   * Tool definition for setup_api_key.
   */
  export const setupApiKeyToolDefinition = {
  	name: 'setup_api_key',
  	description:
  		'Authenticates with your StacksFinder account and creates an API key. Requires Pro or Team tier. The key is returned once and should be saved securely.'
  };