Skip to content

Latest commit

 

History

History
170 lines (134 loc) · 3.88 KB

DEVELOPER_GUIDE.md

File metadata and controls

170 lines (134 loc) · 3.88 KB

Developer Guide: Local Haiven MCP Setup

For developers testing against local Haiven instances

This guide shows how to quickly set up the MCP server for local development with authentication disabled.

Quick Start (5 minutes)

1. Start Local Haiven Backend

Start your local Haiven backend. It should be running at http://localhost:8080

2. Setup MCP Server

# Clone and setup
git clone https://github.com/tw-haiven/haiven-mcp-server
cd haiven-mcp-server
sh ./scripts/install.sh

3. Configure for Local Development

Create a .env file:

HAIVEN_API_URL=http://localhost:8080
HAIVEN_DISABLE_AUTH=true

4. Test the MCP Server

python -m src.mcp_server --help

5. Configure Your AI Tool

Add this MCP server to your AI tool's configuration:

"haiven-dev": {
  "command": "/full/path/to/your/haiven-mcp-server/.venv/bin/python",
  "args": ["/full/path/to/your/haiven-mcp-server/mcp_server.py"],
  "env": {
    "HAIVEN_API_URL": "http://localhost:8080",
    "HAIVEN_DISABLE_AUTH": "true"
  }
}

6. Test in Your AI Tool

Restart your AI tool and ask: "What Haiven prompts are available?"

Development Workflow

Starting Development Session

# Terminal 1: Start Haiven backend
cd haiven && poetry run app

# Terminal 2: Test MCP server
cd haiven-mcp-server && python mcp_server.py --help

Quick Testing

# Direct test of MCP server
cd haiven-mcp-server
export HAIVEN_API_URL="http://localhost:8080"
export HAIVEN_DISABLE_AUTH="true"
python -m src.mcp_server

Testing Different Scenarios

# Test with authentication enabled
export HAIVEN_API_URL="http://localhost:8080"
export HAIVEN_API_KEY="your-dev-api-key"
unset HAIVEN_DISABLE_AUTH

# Test against remote instance
export HAIVEN_API_URL="https://your-remote-haiven.com"
export HAIVEN_API_KEY="your-remote-api-key"

Testing & Debugging

Enable Debug Logging

export PYTHONPATH=.
export HAIVEN_API_URL="http://localhost:8080"
export HAIVEN_DISABLE_AUTH="true"
python -c "
import logging
logging.basicConfig(level=logging.DEBUG)
from mcp_server import HaivenMCPServer
print('Debug logging enabled')
"

Test API Connectivity

curl http://localhost:8080/api/prompts

Common Issues & Solutions

"Connection refused" errors

# Check if Haiven backend is running
curl http://localhost:8080/health

"No prompts found"

# Check if prompts are loaded
curl http://localhost:8080/api/prompts | jq '.[0].id'

MCP server not connecting

# Test basic import
python -c "from mcp_server import HaivenMCPServer; print('OK')"

Development Tips

Multiple Environment Setup

Create different config files:

# dev.env
HAIVEN_API_URL=http://localhost:8080
HAIVEN_DISABLE_AUTH=true

# staging.env
HAIVEN_API_URL=https://staging.haiven.com
HAIVEN_API_KEY=staging-api-key

Load with:

source dev.env && python mcp_server.py

Alternative Entry Point

You can also run from the project root:

python mcp_server.py

Development Checklist

  • Local Haiven backend running
  • MCP server dependencies installed (sh ./scripts/install.sh)
  • Environment variables set
  • AI tool configured with local MCP server
  • Basic connectivity tested
  • MCP server responds to prompts query

Happy local development!

MCP Setup Resources: