MCP Knowledge Vault Search Tool

This tool provides an MCP (Model Context Protocol) server that allows you to search your personal knowledge vault using hybrid semantic and keyword matching. The server connects to the Fondu Knowledge Vault API to retrieve relevant information from your personal knowledge base.

Features

• Hybrid Search: Combines semantic vector search with keyword matching
• Reranking: Uses reranking models to prioritize the most relevant results
• Flexible Authentication: Multiple authentication methods with priority-based resolution
• Production Ready: Comprehensive error handling and logging
• MCP Compatible: Works with Claude Desktop and other MCP clients
• SSE Transport: Server-Sent Events for real-time communication

Prerequisites

• Python 3.8+
• Access to Fondu Knowledge Vault API
• Valid authentication token

Installation

1. Clone this repository:

git clone <repository-url>
cd mcp_tools

2. Set up virtual environment and install dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Authentication Setup

The server supports multiple authentication methods with the following priority order:

1. Explicit Parameter (Highest Priority)

Pass the token directly when calling the tool.

2. Environment Variables

Set one of these environment variables:

export FONDU_AUTH_TOKEN="your-token-here"
# or
export FONDU_API_TOKEN="your-token-here"

3. Configuration Files

Create a config file at one of these locations:

• ~/.fondu/config.yaml (recommended)
• ~/.config/fondu/config.yaml
• config.yaml (in project directory)

Example config file:

fondu:
  auth_token: "your-token-here"
  base_url: "https://api.youfondu.com"

server:
  host: "127.0.0.1"
  port: 8080
  debug: true

4. Token Files

Save your token in one of these files:

• ~/.fondu/token
• ~/.config/fondu/token
• .fondu_token

Starting the MCP Server

Method 1: Direct Python (Recommended)

source .venv/bin/activate
python mcp_fondu_search_user_context/server.py --host 127.0.0.1 --port 8080

Method 2: Using the run script

./run.sh

The server will start on http://127.0.0.1:8080 with the following endpoints:

• / - Homepage
• /health - Health check
• /sse - Server-Sent Events endpoint for MCP
• /messages/ - Message handling endpoint

Claude Desktop Configuration

To use with Claude Desktop, add this to your ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "knowledge_vault": {
      "command": "python",
      "args": ["/absolute/path/to/mcp_tools/mcp_fondu_search_user_context/server.py"],
      "env": {
        "FONDU_AUTH_TOKEN": "your-auth-token-here"
      }
    }
  }
}

Alternative using the run script:

{
  "mcpServers": {
    "knowledge_vault": {
      "command": "/absolute/path/to/mcp_tools/run.sh",
      "env": {
        "FONDU_AUTH_TOKEN": "your-auth-token-here"
      }
    }
  }
}

Available Tools

gather_relevant_user_knowledge

Search your knowledge vault using hybrid semantic and keyword matching.

Parameters:

• query (string, required): Natural language query for semantic search and reranking
• auth_token (string, optional): Authentication token (if not set via env/config)
• keywords (string, optional): Specific terms to prioritize in keyword matching
• top_k (integer, optional): Number of results to return (default: 10)

Returns: A formatted string containing the most relevant results from your knowledge vault, including source information and metadata when available.

Example Response:

Found 3 relevant results in your knowledge vault:

1. Quantum computing uses quantum mechanical phenomena like superposition and entanglement to perform calculations...
Source: quantum_computing_notes.md
Metadata: {'tags': ['physics', 'computing'], 'date': '2024-01-15'}

2. The fundamental principle behind quantum algorithms is the ability to exist in multiple states simultaneously...
Source: research_papers/quantum_algorithms.pdf
Metadata: {'author': 'Dr. Smith', 'year': 2023}

Testing

Server Health Test

curl http://127.0.0.1:8080/health

Tool Functionality Test

Create a test script to verify the tool works:

import asyncio
import sys
sys.path.append('mcp_fondu_search_user_context')

from server import gather_relevant_user_knowledge

async def test_tool():
    result = await gather_relevant_user_knowledge(
        query="machine learning algorithms",
        auth_token="your-token-here",
        top_k=5
    )
    print(result)

asyncio.run(test_tool())

Configuration Examples

Example configuration files are provided:

• config.yaml.example - Server configuration template
• claude_desktop_config.json.example - Claude Desktop setup template

Copy these files and customize with your settings:

cp config.yaml.example ~/.fondu/config.yaml
# Edit with your auth token and preferences

Error Handling and Logging

The server provides comprehensive error handling:

• Missing Auth Token: Clear error message with setup instructions
• API Errors: Graceful handling of network issues and API failures
• Invalid Tokens: Proper 403 error handling
• Debug Logging: Detailed logs for troubleshooting

Logs are written to:

• Standard error output (visible when running the server)
• /tmp/error_log.txt (fallback error logging)

API Configuration

The server connects to:

• Production API: https://api.youfondu.com/v1/knowledge/search_knowledge_vault
• Protocol: HTTPS with Bearer token authentication
• Timeout: 30 seconds for API requests
• Format: JSON request/response

Troubleshooting

Common Issues

1. Authentication Errors

   • Verify your token is valid and not expired
   • Check token is properly set via environment variable or config file
   • Ensure no extra whitespace in token files

2. Connection Issues

   • Verify internet connectivity
   • Check if API endpoint is accessible: curl -I https://api.youfondu.com
   • Ensure no firewall blocking outbound HTTPS

3. MCP Client Issues

   • Restart Claude Desktop after configuration changes
   • Check that absolute paths are used in configuration
   • Verify Python virtual environment is properly activated

4. Server Startup Issues

   • Ensure all dependencies are installed: pip install -r requirements.txt
   • Check port 8080 is not already in use
   • Verify Python 3.8+ is being used

Debug Mode

To enable debug logging, set the environment variable:

export PYTHONPATH=/path/to/mcp_tools
export DEBUG=1
python mcp_fondu_search_user_context/server.py

Testing Authentication Methods

You can test different authentication methods:

# Test with environment variable
export FONDU_AUTH_TOKEN="your-token"
python test_auth.py

# Test with config file
echo "fondu:\n  auth_token: your-token" > ~/.fondu/config.yaml
python test_auth.py

# Test with token file
echo "your-token" > ~/.fondu/token
python test_auth.py

Development

To contribute or modify the server:

1. Setup Development Environment

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   

2. Run Tests

   python test_mcp_server.py
   python test_tool_functionality.py
   

3. Code Structure

   • mcp_fondu_search_user_context/server.py - Main server implementation
   • requirements.txt - Python dependencies
   • run.sh - Convenience script for starting server
   • config.yaml.example - Configuration template
   • claude_desktop_config.json.example - Claude Desktop setup template

Dependencies

Core dependencies:

• fastapi>=0.109.2 - Web framework
• uvicorn>=0.27.1 - ASGI server
• httpx>=0.26.0 - HTTP client
• mcp>=1.3.0 - Model Context Protocol
• PyYAML>=6.0 - YAML configuration support

See requirements.txt for complete dependency list.

Deployment

AWS App Runner

This server is ready for deployment to AWS App Runner. See DEPLOYMENT.md for detailed deployment instructions.

Quick Deploy:

1. Push code to your Git repository
2. Create App Runner service pointing to your repository
3. Set FONDU_AUTH_TOKEN environment variable
4. Deploy!

The server includes:

• ✅ App Runner configuration (apprunner.yaml)
• ✅ Docker support (Dockerfile)
• ✅ Health check endpoint (/health)
• ✅ Environment variable configuration
• ✅ Production-ready logging
• ✅ Auto-scaling support

Other Cloud Platforms

The server can be deployed to any platform that supports:

• Python 3.8+
• Environment variables
• HTTP/HTTPS traffic on port 8080

Tested platforms:

• AWS App Runner ✅
• Docker containers ✅
• Traditional VPS hosting ✅

License

[Add your license information here]