stacksfinder-mcp

Instructions

Implementation Reference

• src/tools/api-keys.ts:164-230 (handler)

  The executeListApiKeys function implements the core logic of the list_api_keys tool. It checks for a configured API key, fetches the user's API keys from the StacksFinder API (/api/v1/keys), handles authentication errors and other failures, parses the response, and formats it as a Markdown table showing key details including name, prefix/suffix, scopes, creation date, last used date, and usage limits.

  export async function executeListApiKeys(): Promise<{ text: string; isError?: boolean }> {
  	const config = getConfig();
  
  	if (!config.apiKey) {
  		return {
  			text: `**Error**: No API key configured. Use \`setup_api_key\` tool first or set STACKSFINDER_API_KEY environment variable.`,
  			isError: true
  		};
  	}
  
  	debug('Listing API keys');
  
  	try {
  		const response = await fetch(`${config.apiUrl}/api/v1/keys`, {
  			method: 'GET',
  			headers: {
  				Authorization: `Bearer ${config.apiKey}`,
  				'Content-Type': 'application/json'
  			}
  		});
  
  		if (!response.ok) {
  			if (response.status === 401) {
  				return {
  					text: '**Error**: Invalid API key. Please reconfigure with a valid key.',
  					isError: true
  				};
  			}
  			const errorText = await response.text();
  			return {
  				text: `**Error**: Failed to list keys (${response.status}): ${errorText}`,
  				isError: true
  			};
  		}
  
  		const data = (await response.json()) as ListKeysResponse;
  
  		let text = `## Your API Keys
  
  **Usage**: ${data.limits.used}/${data.limits.max} keys (${data.limits.remaining} remaining)
  
  | Name | Prefix | Scopes | Created | Last Used |
  |------|--------|--------|---------|-----------|
  `;
  
  		for (const key of data.keys) {
  			const lastUsed = key.lastUsedAt ? new Date(key.lastUsedAt).toLocaleDateString() : 'Never';
  			const created = new Date(key.createdAt).toLocaleDateString();
  			const scopes = key.scopes.join(', ');
  			text += `| ${key.name} | ${key.prefix}...${key.suffix} | ${scopes} | ${created} | ${lastUsed} |\n`;
  		}
  
  		if (data.keys.length === 0) {
  			text += `| (no keys) | - | - | - | - |\n`;
  		}
  
  		text += `\nManage keys at: ${config.apiUrl}/account/developer/api-keys`;
  
  		return { text };
  	} catch (err) {
  		const errorMessage = err instanceof Error ? err.message : 'Failed to list API keys';
  		return {
  			text: `**Error**: ${errorMessage}`,
  			isError: true
  		};
  	}
  }

• src/server.ts:331-351 (registration)

  Registers the list_api_keys tool with the MCP server using listApiKeysToolDefinition.name, sets title, description from the definition, empty inputSchema, read-only annotations, and a handler that calls executeListApiKeys() and returns the text content with isError flag.

  server.registerTool(
  	listApiKeysToolDefinition.name,
  	{
  		title: 'List API Keys',
  		description: listApiKeysToolDefinition.description,
  		inputSchema: {},
  		annotations: {
  			readOnlyHint: true,
  			destructiveHint: false,
  			openWorldHint: false
  		}
  	},
  	async () => {
  		debug('list_api_keys called');
  		const { text, isError } = await executeListApiKeys();
  		return {
  			content: [{ type: 'text', text }],
  			isError
  		};
  	}
  );

• src/tools/api-keys.ts:128-138 (schema)

  Defines the input schema as an empty object (no parameters required) and the tool metadata including name 'list_api_keys' and description. Also exports the inferred TypeScript type.

  export const ListApiKeysInputSchema = z.object({});
  
  export type ListApiKeysInput = z.infer<typeof ListApiKeysInputSchema>;
  
  /**
   * Tool definition for list_api_keys.
   */
  export const listApiKeysToolDefinition = {
  	name: 'list_api_keys',
  	description: 'Lists your StacksFinder API keys. Requires a configured API key.'
  };