feat(init): enable project MCP servers in .claude/settings.json

[divideby0]

Description

ftk init must configure .claude/settings.json to enable project-scoped MCP servers from .mcp.json. Without this configuration, Claude Code will not recognize or load the MCP servers defined in the project's .mcp.json file.

Problem

By default, Claude Code does not automatically load MCP servers from project .mcp.json files for security reasons. Users must explicitly enable project-scoped MCP servers in their .claude/settings.json file.

Result if not configured: MCP servers defined in .mcp.json will be ignored by Claude Code, causing confusion when servers appear configured but don't work.

Solution

During ftk init, create or update .claude/settings.json to enable project MCP servers.

Configuration Options

Three approaches for enabling project MCP servers (from ClaudeLog configuration docs):

Option 1: Enable All (Recommended for ftk)

{
  "enableAllProjectMcpServers": true
}

✅ Automatically approves ALL MCP servers defined in project .mcp.json files
✅ Simplest for users
✅ Best for trusted development environments
⚠️ Requires user trust in project configuration

Option 2: Whitelist Specific Servers

{
  "enabledMcpjsonServers": ["memory", "sequential", "notion"]
}

✅ Whitelist specific servers from .mcp.json files
✅ More granular control
⚠️ Requires maintenance as new servers are added

Option 3: Blacklist Specific Servers

{
  "disabledMcpjsonServers": ["filesystem"]
}

✅ Blacklist risky servers while allowing others
⚠️ Less explicit about what's allowed

Implementation Requirements

1. Create/Update .claude/settings.json

• Check if .claude/settings.json exists
• Create .claude/ directory if it doesn't exist
• Read existing settings if file exists
• Merge new MCP server enablement setting
• Write updated settings back to file
• Preserve existing settings (don't overwrite unrelated config)

2. User Prompt for Security Choice

• Explain security implications to user
• Offer choice between approaches (default: Option 1)
• For Option 2, prompt for which servers to whitelist (default: all selected during init)

3. Settings File Location

Primary location: .claude/settings.json (project-specific, should be gitignored)

Alternative locations (for reference, not recommended):

• ~/.claude/settings.json (user-global)
• ~/.claude/settings.local.json (user-local)
• .claude/settings.local.json (project-local)

Example Implementation

import { ensureDir } from "@std/fs";
import { join } from "@std/path";

async function enableProjectMcpServers(
  projectRoot: string,
  approach: "all" | "whitelist" | "blacklist",
  servers?: string[]
) {
  const settingsDir = join(projectRoot, ".claude");
  const settingsPath = join(settingsDir, "settings.json");

  // Ensure .claude directory exists
  await ensureDir(settingsDir);

  // Read existing settings or start fresh
  let settings: Record<string, unknown> = {};
  try {
    const existing = await Deno.readTextFile(settingsPath);
    settings = JSON.parse(existing);
  } catch {
    // File doesn't exist, start fresh
  }

  // Apply chosen approach
  if (approach === "all") {
    settings.enableAllProjectMcpServers = true;
  } else if (approach === "whitelist" && servers) {
    settings.enabledMcpjsonServers = servers;
  } else if (approach === "blacklist" && servers) {
    settings.disabledMcpjsonServers = servers;
  }

  // Write settings
  await Deno.writeTextFile(
    settingsPath,
    JSON.stringify(settings, null, 2) + "\n"
  );

  console.log("✓ Enabled project MCP servers in .claude/settings.json");
}

User Experience Flow

$ ftk init

...
[After MCP server selection]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Project MCP Server Configuration
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Claude Code requires explicit permission to load MCP servers 
from project .mcp.json files for security.

Choose how to enable project MCP servers:

1. ✓ Enable all servers (recommended for trusted projects)
   Automatically loads all servers in .mcp.json
   
2. Whitelist specific servers
   Only load selected servers: sequential, memory, notion
   
3. Blacklist risky servers
   Load all except specified servers

Your choice: [1]: _

.gitignore Consideration

The .claude/settings.json file should be added to .gitignore as it contains user-specific preferences:

# Claude Code user settings
.claude/settings.json
.claude/settings.local.json

However, ftk init should document this in its setup instructions.

Acceptance Criteria

• ftk init creates .claude/settings.json if it doesn't exist
• User is prompted to choose MCP server enablement approach
• Default choice is "enable all" (Option 1) for simplicity
• Existing settings in .claude/settings.json are preserved
• Settings file is created with proper JSON formatting
• User receives confirmation that project MCP servers are enabled
• MCP servers from .mcp.json are recognized by Claude Code after init
• Documentation explains the security implications

Documentation Updates

• Update docs/quickstart.md to mention .claude/settings.json requirement
• Add section explaining MCP server enablement options
• Document .gitignore recommendation for .claude/settings.json

Validation

After ftk init, verify:

# Check settings file was created
cat .claude/settings.json

# Verify Claude Code recognizes MCP servers
claude mcp list

Related Issues

• feat(mcp-server): Add Notion MCP Server Support with Authentication #2 - Notion MCP support (needs this to work)
• feat(cli): add ftk config command for MCP server management #3 - ftk config command (should also respect these settings)

Reference

• ClaudeLog Configuration Guide