Nerdearla Server

🚀 Live Server: The server is running at https://mcp.nerdear.la/mcp

An MCP (Model Context Protocol) server that provides information about Nerdearla events, speakers, and sessions. Built with FastMCP and supports streamable HTTP in stateless mode with JSON responses.

Quick Start - Add to VS Code Copilot

To use this MCP server with VS Code Copilot:

1. Open the command palette in VS Code (Cmd+Shift+P / Ctrl+Shift+P)
2. Type "MCP: Add Server" and select it
3. Select "HTTP" as the server type
4. Enter the server URL: https://mcp.nerdear.la/mcp
5. Give it a name, any name is fine
6. Select if you want to save it in your user or workspace settings

You can now ask Copilot about Nerdearla events, speakers, and sessions!

Quick Start - Add to your favourite Agent/IDE

Most Agents/IDEs support MCP servers out of the box. Check your documentation for instructions on how to add a new server.

Local Developtment Setup

This project uses uv for dependency management. Make sure you have uv installed:

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

Then install the project dependencies:

# Clone and navigate to the repository
cd nerdearla-mcp

# Install dependencies with uv
uv sync

Usage

Running the Server

Start the MCP server:

# Using uv
uv run nerdearla-mcp

# Or directly with Python
uv run python -m nerdearla_mcp.server

The server will start on http://localhost:8000/mcp by default.

Development

Project Structure

nerdearla-mcp/
├── nerdearla_mcp/
│   ├── __init__.py
│   └── server.py          # Main MCP server implementation
├── pyproject.toml         # Project configuration and dependencies
├── README.md              # This file
└── ...

Adding New Tools

To add new tools to the server:

1. Define your tool function in nerdearla_mcp/server.py
2. Use the @mcp.tool() decorator
3. Add proper type hints and docstrings
4. Implement the tool to retrieve the data from an API, file or database as needed

Example:

@mcp.tool()
def get_sponsors(tier: Optional[str] = None) -> List[Dict[str, Any]]:
    """
    Get information about event sponsors.
    
    Args:
        tier: Optional filter by sponsor tier (e.g., "Gold", "Silver", "Bronze")
    
    Returns:
        List of sponsor information
    """
    # Implementation here
    pass

Running Tests

# Run tests with pytest
uv run pytest

Code Formatting

Pre-commit Hooks (Recommended)

This project uses pre-commit hooks to automatically format and lint code before commits:

Install pre-commit hooks:

# Install dependencies (includes pre-commit)
uv sync

# Install the git hooks
uv run pre-commit install

Usage:

• Hooks run automatically on git commit
• To run manually on all files: uv run pre-commit run --all-files
• To skip hooks for a commit: git commit --no-verify

The hooks will automatically:

• Format code with Black
• Lint and fix issues with Ruff
• Format code with Ruff formatter

Configuration

Port Configuration

The server runs on port 8000 by default. You can configure the port using environment variables:

Environment Variable:

export PORT=3000
uv run nerdearla-mcp

Using .env file: Create a .env file in the project root:

PORT=3000

Priority order:

1. Environment variable PORT
2. .env file
3. Default: 8000

Server Configuration

The server uses streamable HTTP transport with the following default settings:

• Host: 0.0.0.0 (accepts connections from any IP)
• Port: as described above
• Path: /mcp (API endpoint)
• Transport: streamable-http
• Mode: stateless_http=True

Contributing

1. Fork the repository
2. Make your changes
3. Add tests if applicable
4. Run the linter and formatter
5. Submit a pull request

License

See the LICENSE file for details.