Skip to content

MCP_SETUP_GUIDE.md

Latest commit

 

History

History
297 lines (221 loc) · 6.39 KB

MCP_SETUP_GUIDE.md

File metadata and controls

297 lines (221 loc) · 6.39 KB

🔌 MCP Setup Guide for EIGHT

What is MCP?

Model Context Protocol (MCP) is a standardized way to connect AI applications to external tools and data sources. For EIGHT, MCP enables:

  • Real-time web search for dynamic recommendations
  • Content fetching from external APIs
  • Multi-source data aggregation
  • Enhanced AI responses with live data

Current MCP Configuration

EIGHT is configured with two MCP servers:

1. Fetch Server (Active)

  • Package: @modelcontextprotocol/server-fetch
  • Purpose: Fetch web content and API data
  • Status: ✅ Enabled by default
  • No API key required

2. Brave Search (Optional)

  • Package: @modelcontextprotocol/server-brave-search
  • Purpose: Real-time web search for recommendations
  • Status: ⚠️ Disabled (requires API key)
  • Get API key: https://brave.com/search/api/

Setup Instructions

Step 1: Verify MCP Configuration

Check .kiro/settings/mcp.json:

{
  "mcpServers": {
    "fetch": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"],
      "disabled": false
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${VITE_BRAVE_API_KEY}"
      },
      "disabled": true
    }
  }
}

Step 2: Install MCP Servers (Optional)

MCP servers are installed automatically via npx, but you can pre-install them:

# Install fetch server
npm install -g @modelcontextprotocol/server-fetch

# Install brave search server (if you have API key)
npm install -g @modelcontextprotocol/server-brave-search

Step 3: Get Brave API Key (Optional)

  1. Visit https://brave.com/search/api/
  2. Sign up for a free account
  3. Get your API key
  4. Add to .env:
VITE_BRAVE_API_KEY=your_brave_api_key_here
  1. Enable in .kiro/settings/mcp.json:
"brave-search": {
  "disabled": false  // Change from true to false
}

Step 4: Test MCP Connection

Run the test utility in your browser console:

import { testMCPConnection } from './src/utils/mcpTest'

testMCPConnection()

Expected output:

🔌 Testing MCP Connections...

Testing @modelcontextprotocol/server-fetch...
✅ Fetch MCP server configured

Testing @modelcontextprotocol/server-brave-search...
⚠️  Brave API key not configured (optional)

📊 MCP Connection Summary:
   Fetch Server: ✅
   Brave Search: ⚠️  (optional)

Using MCP in Kiro

In Kiro IDE

Once MCP is configured, Kiro can automatically use these tools:

Example 1: Ask Kiro to search

You: "Search for the best ramen restaurants in Tokyo"
Kiro: *uses brave_web_search MCP tool*
Kiro: "I found 5 top-rated ramen spots..."

Example 2: Ask Kiro to fetch data

You: "Fetch the weather forecast from this API"
Kiro: *uses fetch MCP tool*
Kiro: "Here's the forecast data..."

In Your Code

You can also use MCP tools programmatically (when Kiro implements them):

// Example: Enhanced oracle with MCP search
const getEnhancedRecommendation = async (question: string, context: Context) => {
  // Kiro would implement this using MCP
  const searchResults = await mcp.call('brave_web_search', {
    query: `${question} ${context.weather} ${context.location}`
  })
  
  return generateOracleResponse(searchResults)
}

MCP Tools Available

Fetch Server Tools

  • fetch: Fetch content from any URL 
    mcp.call('fetch', { url: 'https://api.example.com/data' })

Brave Search Tools

  • brave_web_search: Search the web 
    mcp.call('brave_web_search', { 
  query: 'best pizza in New York',
  count: 10 
})

Troubleshooting

MCP Server Not Found

Error: Cannot find module '@modelcontextprotocol/server-fetch'

Solution:

# Clear npm cache
npm cache clean --force

# Try running with npx (will auto-install)
npx -y @modelcontextprotocol/server-fetch

Brave API Key Not Working

Error: Invalid API key

Solution:

  1. Verify key in .env file
  2. Check key is active at https://brave.com/search/api/
  3. Restart development server
  4. Check MCP server logs in Kiro

MCP Server Disconnected

Error: MCP server connection lost

Solution:

  1. Check internet connection
  2. Restart Kiro IDE
  3. Verify MCP configuration in .kiro/settings/mcp.json
  4. Check MCP server status in Kiro's MCP panel

Advanced Configuration

Auto-Approve Tools

To avoid manual approval for each MCP call:

{
  "mcpServers": {
    "brave-search": {
      "autoApprove": ["brave_web_search"],  // Auto-approve this tool
      "disabledTools": []  // Disable specific tools if needed
    }
  }
}

Environment Variables

Use environment variables for sensitive data:

{
  "env": {
    "BRAVE_API_KEY": "${VITE_BRAVE_API_KEY}",  // From .env
    "CUSTOM_API_KEY": "${VITE_CUSTOM_KEY}"
  }
}

Multiple MCP Servers

Add more MCP servers as needed:

{
  "mcpServers": {
    "fetch": { ... },
    "brave-search": { ... },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Benefits for EIGHT

Without MCP

  • ❌ Fixed database of recommendations
  • ❌ Static, pre-defined options
  • ❌ No real-time data
  • ❌ Limited variety

With MCP

  • ✅ Unlimited recommendations via search
  • ✅ Real-time, fresh data
  • ✅ Dynamic, context-aware results
  • ✅ Infinite variety

Example Comparison

Question: "What should I eat?"

Without MCP:

Response: "Hot ramen warms the soul."
Link: Generic UberEats search

With MCP:

Response: "Tonkotsu ramen at Ichiran, 0.3 mi. 
          Open now, 4.8★ rating. Rain demands rich broth."
Link: Direct link to Ichiran on UberEats

Next Steps

  1. ✅ MCP is configured (fetch server active)
  2. ⚠️ Get Brave API key (optional but recommended)
  3. 🔄 Test MCP connection
  4. 🚀 Use MCP in Kiro for enhanced development

Resources

Ready to use MCP? Start by testing the fetch server, then add Brave Search for unlimited recommendations! 🎱✨