skvil-mcp

Instructions

Implementation Reference

• src/tools.ts:245-290 (registration)

  Tool registration for skvil_register. Registers the tool with the MCP server, including description and handler function that checks for existing API keys and calls api.register().

  // ── skvil_register ────────────────────────────────────────────────────────
  server.tool(
    'skvil_register',
    'Register for a free Skvil API key. The key is automatically cached ' +
      'locally for future use. No sign-up or account required. Other tools ' +
      '(skvil_scan, skvil_report) will use the cached key automatically.',
    {},
    async () => {
      try {
        const existing = getApiKey();
        if (existing) {
          return {
            content: [
              {
                type: 'text',
                text:
                  'An API key is already configured.\n\n' +
                  'To register a new key, unset the `SKVIL_API_KEY` env var and ' +
                  'delete `~/.skvil/mcp-config.json`, then try again.',
              },
            ],
          };
        }
  
        const result = await api.register();
        return {
          content: [
            {
              type: 'text',
              text:
                '**API key registered successfully!**\n\n' +
                `- **Key prefix:** ${result.key_prefix}...\n` +
                `- **Tier:** ${result.tier}\n\n` +
                'The key has been cached in `~/.skvil/mcp-config.json`.\n' +
                'You can now use `skvil_scan` and `skvil_report`.',
            },
          ],
        };
      } catch (error) {
        return {
          content: [{ type: 'text', text: formatError('register', error) }],
          isError: true,
        };
      }
    },
  );

• src/api.ts:144-149 (handler)

  Core API handler that makes a POST request to /register endpoint, saves the API key locally, and returns the registration result with key prefix and tier.

  /** Register for a free API key and cache it locally. */
  export async function register(): Promise<RegisterResponse> {
    const result = await request<RegisterResponse>('POST', '/register');
    saveApiKey(result.api_key, result.key_prefix);
    return result;
  }

• src/types.ts:35-39 (schema)

  Type definition for the RegisterResponse schema that defines the structure of the API registration response including api_key, key_prefix, and tier fields.

  export interface RegisterResponse {
    api_key: string;
    key_prefix: string;
    tier: string;
  }

• src/config.ts:78-86 (helper)

  Helper function that saves the newly registered API key to ~/.skvil/mcp-config.json along with key prefix and registration timestamp. Updates the in-memory cache.

  /** Cache a newly registered API key for future use. */
  export function saveApiKey(apiKey: string, keyPrefix: string): void {
    const config = readConfig();
    config.api_key = apiKey;
    config.key_prefix = keyPrefix;
    config.registered_at = new Date().toISOString();
    writeConfig(config);
    cachedApiKey = apiKey;
  }