jonathancrawford05/mcp-server

FastMCP Documentation Server

A Model Context Protocol (MCP) server that provides intelligent documentation search capabilities for popular development libraries using the Serper API.

Overview

This FastMCP server enables AI assistants to search and retrieve documentation from various development libraries including Langchain, OpenAI, MCP, and Llama-Index. It uses the Serper API for web searches and intelligently extracts relevant content from documentation pages.

Features

• Multi-Library Support: Search documentation for Langchain, OpenAI, MCP, and Llama-Index
• Smart Content Extraction: Uses BeautifulSoup to extract main content while filtering out navigation and sidebars
• Async Operations: Built with async/await for efficient concurrent requests
• Content Limiting: Automatically truncates large responses to prevent overwhelming output
• Error Handling: Gracefully handles HTTP errors, timeouts, and missing content

Requirements

• Python: >= 3.11.9
• uv: Modern Python package manager
• API Key: Serper API key for web searches

Dependencies

Dependencies are managed via pyproject.toml and automatically installed with uv:

• beautifulsoup4 >= 4.13.4
• httpx >= 0.28.1
• mcp[cli] >= 1.9.0
• python-dotenv >= 1.1.0

Installation

1. Clone the repository and navigate to the project directory:

   cd ~/projects/claude-mcp/mcp-server
   

2. Ensure Python 3.11.9+ is installed:

   python --version
   

3. Install uv (if not already installed):

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

4. Install dependencies:

   uv sync
   

5. Configure environment variables:

   cp example_env .env
   

   Then edit .env and add your Serper API key:

   SERPER_API_KEY=your_actual_api_key_here
   

Usage

Option 1: Using the Startup Script (Recommended)

The easiest way to start the server:

./start_mcp.sh

This script automatically:

• Navigates to the correct directory
• Activates the virtual environment
• Starts the MCP development server
• Provides helpful error messages if something goes wrong

Option 2: Manual Startup

# Activate the virtual environment
source .venv/bin/activate

# Start the MCP development server
mcp dev main.py

Option 3: Direct Execution with uv

uv run mcp dev main.py

Supported Libraries

The server currently supports documentation searches for:

API Reference

get_docs(query: str, library: str) -> str

Search documentation for a specific query within a supported library.

Parameters:

• query (str): The search query (e.g., "Chroma DB", "embeddings", "streaming")
• library (str): The library to search in. Must be one of: langchain, openai, mcp, llama-index

Returns:

• str: Formatted text containing relevant documentation with source URLs

Example:

result = await get_docs("Chroma DB", "langchain")

Raises:

• ValueError: If the specified library is not supported

How It Works

1. Query Construction: Combines your query with the library's documentation site URL
2. Web Search: Uses Serper API to find the top 2 most relevant documentation pages
3. Content Fetching: Retrieves the full HTML content of each result
4. Content Extraction: Uses BeautifulSoup to extract main content, filtering out navigation and sidebars
5. Response Formatting: Combines results with clear source attribution and separators

Configuration

Environment Variables

• SERPER_API_KEY: Your API key for the Serper search service (required)

Customization

You can modify these settings in main.py:

• USER_AGENT: HTTP user agent string (default: "docs-app/1.0")
• SERPER_URL: Serper API endpoint
• docs_urls: Dictionary mapping library names to their documentation URLs
• Content length limit: Maximum 8000 characters per page (can be adjusted)
• Number of results: Currently fetches top 2 results (adjustable in search_web function)

Error Handling

The server includes comprehensive error handling:

• HTTP Errors: Caught and reported with status information
• Timeouts: 30-second timeout for all HTTP requests
• No Results: Returns "No results found" if search yields no results
• Unsupported Library: Raises ValueError with list of supported libraries
• Content Extraction: Falls back to full page text if main content can't be identified

Limitations

• Library Coverage: Currently supports only four libraries (Langchain, OpenAI, MCP, Llama-Index)
• Content Length: Responses are limited to 8000 characters per page to prevent overwhelming output
• Search Results: Returns only the top 2 most relevant pages
• Website Structure: Content extraction may vary based on documentation site structure

Future Improvements

• Add support for additional documentation sources
• Implement intelligent caching to reduce API calls
• Add configuration file for easy customization
• Improve content extraction for various documentation formats
• Add support for searching across multiple libraries simultaneously
• Implement rate limiting and request throttling
• Add logging for debugging and monitoring
• Support for local documentation sources

Project Structure

mcp-server/
├── main.py           # Main server implementation
├── pyproject.toml    # Project configuration and dependencies
├── uv.lock          # Locked dependency versions
├── .python-version  # Python version specification
├── .env             # Environment variables (not in git)
├── example_env      # Example environment file
├── start_mcp.sh     # Startup script
├── .venv/           # Virtual environment (created by uv)
└── README.md        # This file

Troubleshooting

Virtual Environment Issues

If you encounter virtual environment errors:

# Remove existing virtual environment
rm -rf .venv

# Recreate with uv
uv sync

Import Errors

If you see import errors, ensure all dependencies are installed:

uv sync --reinstall

Serper API Issues

If searches aren't working:

1. Verify your .env file exists and contains SERPER_API_KEY
2. Check that your API key is valid
3. Ensure you have API credits remaining

License

This project is licensed under the MIT License.

Acknowledgments

• FastMCP: For providing an excellent framework for building MCP servers
• Serper: For providing the web search API
• httpx: For modern async HTTP client capabilities
• BeautifulSoup: For robust HTML parsing and content extraction

Contributing

Contributions are welcome! Feel free to submit issues or pull requests to improve the server.

For questions or issues, please open an issue on the project repository.