feat(registry): add Exa MCP server authentication setup

[divideby0]

Summary

Adds authentication setup for Exa MCP server to enable AI-powered semantic search, deep research, and comprehensive intelligence gathering capabilities from Claude Code.

Implementation Plan

See docs/features/007-exa-authentication.md for detailed implementation approach.

Key Components

1. Registry Updates:

   • Update registry/mcp-servers/exa/index.ts
   • Add configure() lifecycle method
   • Implement API key prompt with validation

2. Authentication Flow:

   • Interactive prompt for Exa API key
   • Validate key format (starts with exa_)
   • Store in .env.mcp.secrets as EXA_API_KEY
   • Update MCP config to use dotenv-cli for env vars

3. Documentation:

   • Update registry/mcp-servers/exa/claude.md
   • Document authentication setup process
   • Include Exa capabilities and use cases
   • Add troubleshooting guide

4. CLAUDE.md Integration:

   • Comprehensive Exa usage examples
   • When to use Exa vs other research tools
   • Deep research workflow documentation
   • Cost considerations

Technical Approach

export const exaServer: MCPServer = {
  name: "exa",
  displayName: "Exa Research",
  description: "AI-powered semantic search and deep research",

  async configure(ctx: SetupContext): Promise<void> {
    ctx.info(`
Get your Exa API key at: https://exa.ai

Exa provides:
- Semantic web search with intent understanding
- Deep research with AI synthesis (exa-research, exa-research-pro)
- Company intelligence and LinkedIn search
- Code documentation and examples
    `);

    const apiKey = await ctx.prompt({
      type: "input",
      name: "EXA_API_KEY",
      message: "Enter your Exa API key:",
      validate: (value: string) => {
        if (!value.startsWith("exa_")) {
          return "Exa API keys should start with 'exa_'";
        }
        if (value.length < 20) {
          return "API key appears too short";
        }
        return true;
      }
    });

    await ctx.saveSecret("EXA_API_KEY", apiKey);
  },

  install(ctx: SetupContext): MCPConfig {
    return {
      type: "stdio",
      command: "npx",
      args: [
        "-y",
        "dotenv-cli",
        "-e",
        ".env.mcp.secrets",
        "--",
        "npx",
        "-y",
        "@modelcontextprotocol/server-exa"
      ],
      env: {}
    };
  }
};

Testing Strategy

• ✅ Test with valid Exa API key
• ✅ Test with invalid key format (missing exa_ prefix)
• ✅ Test with missing API key
• ✅ Verify deep research capabilities work
• ✅ Test web search and company research
• ✅ Test crawling and code context features
• ✅ Verify CLAUDE.md instructions are clear

Exa Capabilities

Deep Research

• Models: exa-research (15-45s, good for most queries), exa-research-pro (45s-2min, comprehensive)
• Workflow: deep_researcher_start → poll with deep_researcher_check
• Output: Comprehensive analysis with sources and citations

Semantic Search

• web_search_exa: Intent-aware web search
• company_research_exa: Business intelligence
• linkedin_search_exa: Professional profiles and company pages
• get_code_context_exa: Technical docs and code examples

Content Extraction

• crawling_exa: URL-based extraction with semantic processing

Areas Requesting Feedback

1. API Key Testing

Question: Should we test the API key during setup?

Pros:

• Immediate validation of credentials
• Better user experience (fail fast)
• Can provide specific error messages

Cons:

• Requires network call during setup
• Slower setup process
• May fail due to network issues

Recommendation: Optional validation with --skip-validation flag

2. Rate Limit Communication

Question: How should we handle API rate limits and quota?

Considerations:

• Exa has usage-based pricing
• Deep research is more expensive than simple searches
• Users should understand cost implications

Options:

• A) Display cost warnings during setup
• B) Document in CLAUDE.md only
• C) Add usage tracking/monitoring
• D) Rate limit warnings in real-time

Recommendation: Combination of A and B

3. Cost Documentation

Question: Should we document cost implications of deep research?

Context:

• exa-research-pro is more comprehensive but slower/costlier
• Users should understand trade-offs
• May affect model selection decisions

Proposal: Add cost comparison table in documentation

4. Example Queries

Question: What example queries should we prioritize in documentation?

Categories:

• Research use cases
• Code documentation lookup
• Company intelligence
• Professional networking

Recommendation: Include all categories with practical examples

Related Issues

Closes #7

Checklist

• Implementation plan documented
• Registry entry updated with configure method
• API key validation implemented
• MCP config updated for dotenv-cli
• CLAUDE.md fragment updated
• Tests added
• Documentation complete
• Manually tested with real Exa API key

---

Status: 🚧 Draft - Implementation plan complete, awaiting feedback before coding