feat(registry): add Context7 optional API key configuration

[divideby0]

Summary

Adds optional API key configuration for Context7 MCP server. Context7 works without a key but has rate limits; providing an API key unlocks higher quota and priority access for library documentation lookups.

Implementation Plan

See docs/features/008-context7-auth.md for detailed implementation approach.

Key Components

1. Registry Updates:

   • Update registry/mcp-servers/context7/index.ts
   • Add optional configure() lifecycle method
   • Implement conditional API key prompt

2. Authentication Flow:

   • Ask if user wants to configure API key (optional)
   • Clearly communicate benefits (higher rate limits, priority)
   • Store in .env.mcp.secrets as CONTEXT7_API_KEY if provided
   • Support both with-key and without-key configurations

3. Documentation:

   • Update registry/mcp-servers/context7/claude.md
   • Document optional authentication
   • Explain rate limit differences
   • Include instructions for getting API key

4. Configuration Generation:

   • Generate different MCP configs based on presence of API key
   • Without key: Direct npx invocation
   • With key: dotenv-cli wrapper for environment variables

Technical Approach

export const context7Server: MCPServer = {
  name: "context7",
  displayName: "Context7",
  description: "Up-to-date library documentation and code examples",

  async configure(ctx: SetupContext): Promise<void> {
    ctx.info(`
Context7 provides access to up-to-date library documentation and code examples.

API Key (Optional):
- Without key: Limited requests per IP
- With key: Higher quota and priority access

Get your API key at: https://context7.dev
    `);

    const useApiKey = await ctx.confirm({
      message: "Do you want to configure a Context7 API key?",
      default: false
    });

    if (useApiKey) {
      const apiKey = await ctx.prompt({
        type: "input",
        name: "CONTEXT7_API_KEY",
        message: "Enter your Context7 API key:"
      });

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

  install(ctx: SetupContext): MCPConfig {
    const hasApiKey = ctx.hasSecret("CONTEXT7_API_KEY");

    if (hasApiKey) {
      return {
        type: "stdio",
        command: "npx",
        args: [
          "-y",
          "dotenv-cli",
          "-e",
          ".env.mcp.secrets",
          "--",
          "npx",
          "-y",
          "@modelcontextprotocol/server-context7"
        ],
        env: {}
      };
    } else {
      return {
        type: "stdio",
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-context7"],
        env: {}
      };
    }
  }
};

Testing Strategy

• ✅ Test with API key provided
• ✅ Test without API key (skipped)
• ✅ Test rate limits with and without key
• ✅ Verify both MCP configurations work correctly
• ✅ Test library documentation lookups
• ✅ Test resolve-library-id and get-library-docs workflow
• ✅ Verify CLAUDE.md instructions are clear

Context7 Capabilities

Library Documentation

• resolve-library-id: Find Context7-compatible library ID from package name
• get-library-docs: Fetch documentation with optional topic focus

Use Cases

• Official framework documentation (React, Vue, Angular, Next.js, etc.)
• API reference lookup and exploration
• Code example discovery from real libraries
• Best practices and design patterns
• Version-specific documentation

Rate Limits

• Without API Key: Limited requests per IP address
• With API Key: Higher quota, priority access, better reliability

Areas Requesting Feedback

1. API Key Recommendation

Question: Should we more strongly recommend getting an API key?

Current Approach: Optional with neutral default (false)

Alternatives:

• A) Recommend getting key upfront in messaging
• B) Keep neutral, let users decide
• C) Default to yes, users can skip

Consideration: Context7 works fine without a key for light usage

Recommendation: Option B - keep neutral, document benefits clearly

2. Rate Limit Prominence

Question: How prominently should we display rate limit information?

Options:

• A) Mention during every setup
• B) Document in CLAUDE.md only
• C) Warning on first rate limit hit
• D) Combination approach

Recommendation: Combination of A and B

3. Adding Key Later

Question: Should we support adding an API key later without re-running init?

Use Cases:

• User starts without key, hits rate limits
• User upgrades to paid Context7 plan
• Testing scenarios

Implementation Options:

• A) Manual: User edits .env.mcp.secrets and .mcp.json
• B) Command: ftk configure context7
• C) Re-run: ftk init to reconfigure

Recommendation: Start with A (manual), add B in future if needed

4. Rate Limit Handling

Question: How should we handle rate limit exceeded scenarios during usage?

Context:

• Context7 returns specific error codes
• Claude Code displays errors to user
• Could provide actionable guidance

Options:

• A) Document expected errors in CLAUDE.md
• B) No special handling (user sees raw errors)
• C) Custom error messages (requires MCP server changes)

Recommendation: Option A - document in CLAUDE.md with troubleshooting

Related Issues

Closes #8

Checklist

• Implementation plan documented
• Registry entry updated with optional configure
• Conditional API key prompt implemented
• Dual MCP config generation (with/without key)
• CLAUDE.md fragment updated
• Tests added for both scenarios
• Documentation complete
• Manually tested both paths

---

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