feat(registry): add Notion MCP server support

[divideby0]

Summary

Adds Notion MCP server to the registry with authentication setup and comprehensive usage documentation, enabling interaction with Notion databases and pages from Claude Code.

Implementation Plan

See docs/features/002-notion-mcp-server.md for detailed implementation approach.

Key Components

1. Registry Entry: registry/mcp-servers/notion/

   • index.ts with complete lifecycle methods
   • Precheck for Node.js/npm availability
   • Configure method for Notion integration token
   • Install method generating MCP config

2. Authentication Setup:

   • Interactive prompts for Notion credentials
   • Integration token (required)
   • Optional database IDs for quick access
   • Secure storage in .env.mcp.secrets

3. Documentation:

   • claude.md fragment with usage examples
   • Notion API capabilities overview
   • Troubleshooting guide
   • Links to Notion developer documentation

Technical Approach

export const notionServer: MCPServer = {
  name: "notion",
  displayName: "Notion",
  description: "Interact with Notion databases and pages",

  async configure(ctx: SetupContext): Promise<void> {
    const token = await ctx.prompt({
      type: "input",
      name: "NOTION_API_TOKEN",
      message: "Enter your Notion integration token:",
      validate: (value: string) => {
        if (!value || value.length < 10) {
          return "Please enter a valid Notion integration token";
        }
        return true;
      }
    });

    await ctx.saveSecret("NOTION_API_TOKEN", token);
  },

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

Testing Strategy

• ✅ Test with valid Notion integration token
• ✅ Test with invalid/malformed token
• ✅ Test MCP server installation via npm
• ✅ Verify CLAUDE.md instructions are clear and actionable
• ✅ Test database query capabilities
• ✅ Test page creation and updates
• ✅ Verify error handling for API failures

Areas Requesting Feedback

1. Database Pre-Configuration

Question: Should we prompt users to configure specific Notion databases during initial setup?

Pros:

• Faster access to commonly used databases
• Better out-of-box experience
• Can validate database access immediately

Cons:

• More complex setup flow
• Users may not know database IDs upfront
• Can be configured later as needed

Proposal: Skip for v1, document how to find database IDs

2. Rate Limit Handling

Question: How should we handle Notion API rate limits?

Considerations:

• Notion has per-workspace rate limits
• Rate limit headers included in responses
• Need to communicate limits to users

Options:

• A) Document rate limits in CLAUDE.md
• B) Add rate limit detection in configure
• C) Let users discover through usage

3. Multi-Workspace Support

Question: Should we support multiple Notion workspaces?

Use Cases:

• Personal vs work workspaces
• Multiple client workspaces
• Testing vs production

Implementation:

• Could use server name suffixes (notion-work, notion-personal)
• Or prompt for workspace during configure

4. Capability Prioritization

Question: Which Notion capabilities should be documented first?

Options (vote with 👍):

• A) Database queries and filters
• B) Page creation and updates
• C) Block manipulation
• D) Search across workspace
• E) All of the above equally

Related Issues

Closes #2

Checklist

• Implementation plan documented
• Registry entry created
• Authentication flow implemented
• CLAUDE.md fragment created
• Tests added
• Documentation updated
• Manually tested with real Notion workspace

---

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