Skip to main content
Glama
mcp-server

mcp-server

by SAS-AII

AI Makerspace: MCP Session Repo for Session 13

This project is a demonstration of the MCP (Model Context Protocol) server, which utilizes the Tavily API for web search capabilities. The server is designed to run in a standard input/output (stdio) transport mode.

Related MCP server: metasearch-mcp

Project Overview

The MCP server is set up to handle web search queries using the Tavily API. It is built with the following key components:

  • TavilyClient: A client for interacting with the Tavily API to perform web searches.

Prerequisites

  • Python 3.13 or higher

  • A valid Tavily API key

⚠️NOTE FOR WINDOWS:⚠️

You'll need to install this on the Windows side of your OS.

This will require getting two CLI tool for Powershell, which you can do as follows:

  • winget install astral-sh.uv

  • winget install --id Git.Git -e --source winget

After you have those CLI tools, please open Cursor into Windows.

Then, you can clone the repository using the following command in your Cursor terminal:

git clone https://AI-Maker-Space/AIE7-MCP-Session.git

After that, you can follow from Step 2. below!

Installation

  1. Clone the repository:

    git clone <repository-url>
    cd <repository-directory>
  2. Configure environment variables: Copy the .env.sample to .env and add your Tavily API key:

    TAVILY_API_KEY=your_api_key_here
  3. πŸ—οΈ Add a new tool to your MCP Server πŸ—οΈ

Create a new tool in the server.py file, that's it!

Running the MCP Server

To start the MCP server, you will need to add the following to your MCP Profile in Cursor:

NOTE: To get to your MCP config. you can use the Command Pallete (CMD/CTRL+SHIFT+P) and select "View: Open MCP Settings" and replace the contents with the JSON blob below.

{
    "mcpServers":  {
        "mcp-server": {
            "command" : "uv",
            "args" : ["--directory", "/PATH/TO/REPOSITORY", "run", "server.py"]
        }
    }
}

The server will start and listen for commands via standard input/output.

Usage

The server provides a web_search tool that can be used to search the web for information about a given query. This is achieved by calling the web_search function with the desired query string.

Activities:

There are a few activities for this assignment!

πŸ—οΈ Activity #1: βœ…

  • Built an MCP tool for the Chess.com API to fetch player details and ratings.

  • Implemented as chess_player_stats in server.py and routed via chess_router.py.

πŸ—οΈ Activity #2: LangGraph + MCP Chess App βœ…

  • Implemented a LangGraph ReAct agent that connects to the local MCP server and automatically selects chess tools for natural-language queries.

  • Requirements:

    • Install Stockfish and ensure stockfish is in your PATH (or set STOCKFISH_PATH in .env).

    • Set .env variables: OPENAI_API_KEY, CHESS_USERNAME. Optional: TAVILY_API_KEY, STOCKFISH_PATH.

  • Run:

    uv run main.py

Available Tools

10 tools
chessA

Unified Chess tool (prefer the specific chess_* tools instead).

Supported actions and params:

  • recent_matches: {"limit": int = 5}

  • last_match: {}

  • player_stats: {}

  • analyze_recent_game: {"game_index": int = 0, "movetime_ms": int = 500}

  • analyze_pgn: {"pgn_string": str, "movetime_ms": int = 500}

  • analyze_multiple_pgn: {"pgn_strings": str, "movetime_ms": int = 500}

Examples:

  • chess("recent_matches", {"limit": 3})

  • chess("player_stats")

  • chess("analyze_recent_game", {"game_index": 0, "movetime_ms": 700})

  • chess("analyze_pgn", {"pgn_string": "[Event ...] 1. e4 e5 ...", "movetime_ms": 500})

  • chess("analyze_multiple_pgn", {"pgn_strings": "PGN1 --- PGN2"})

Inputs: action (required), params. Returns: result

chess_analyze_game_idA

Analyze a Chess.com game by its game ID using Stockfish.

Parameters:

  • game_id: The Chess.com game ID (UUID or numeric) from the game's URL

  • movetime_ms: Time per move for engine analysis (default 500)

Example:

  • chess_analyze_game_id("141227700772", 300)

Inputs: game_id (required), movetime_ms. Returns: result

chess_analyze_multiple_pgnA

Analyze multiple PGNs separated by '---', '###', or triple newlines.

Parameters:

  • pgn_strings: One or more PGNs separated by a supported delimiter

  • movetime_ms: Time per move for engine analysis (default 500)

Example:

  • chess_analyze_multiple_pgn("PGN1 --- PGN2", 300)

Inputs: pgn_strings (required), movetime_ms. Returns: result

chess_analyze_pgnC

Analyze a single PGN string with Stockfish.

Parameters:

  • pgn_string: The PGN of the game to analyze

  • movetime_ms: Time per move for engine analysis (default 500)

Example:

  • chess_analyze_pgn("[Event ...] 1. e4 e5 ...", 300)

Inputs: pgn_string (required), movetime_ms. Returns: result

chess_analyze_recent_gameC

Run engine analysis on one of your recent games (0 = latest).

Parameters:

  • game_index: Which recent game to analyze (0 = latest)

  • movetime_ms: Time per move for engine analysis in milliseconds (default 500)

Example:

  • chess_analyze_recent_game(0, 700)

Inputs: game_index, movetime_ms. Returns: result

chess_last_matchA

Show details about your most recent finished game.

Example:

  • chess_last_match()

Inputs: no named parameters. Returns: result

chess_player_statsC

Get your Chess.com profile and ratings summary.

Example:

  • chess_player_stats()

Inputs: no named parameters. Returns: result

chess_recent_matchesB

List your most recent games.

Parameters:

  • limit: Number of games to list (default 5)

Example:

  • chess_recent_matches(3)

Inputs: limit. Returns: result

roll_diceA

Roll dice with the given notation.

Parameters:

  • notation: Dice notation like "2d6+1"

  • num_rolls: Number of times to roll (default 1)

Example:

  • roll_dice("3d6", 2)

Inputs: notation (required), num_rolls. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 10 tools

    Disambiguation3/5

    Most chess tools are clearly distinct (stats, matches, analysis by PGN or ID), but the generic 'chess' tool duplicates all their functionality, creating ambiguity about which tool to use. web_search and roll_dice are unrelated and easy to distinguish.

    Naming Consistency3/5

    web_search and roll_dice use verb_noun pattern consistently. Chess tools mostly follow chess_verb_noun but include exceptions like 'chess_player_stats' (noun_noun) and 'chess_recent_matches' (adjective_noun). The plain 'chess' tool breaks the pattern entirely.

    Tool Count3/5

    10 tools is a reasonable number, but the inclusion of the redundant 'chess' tool and the mix of unrelated domains (web search, dice, chess) makes the surface feel slightly bloated. Could be streamlined by removing the generic chess tool.

    Completeness3/5

    The chess subdomain covers stats, recent matches, and PGN analysis well, but lacks features like game archiving or move-by-move play. web_search and roll_dice are single-purpose and complete. Overall the surface is adequate but not deep in any area.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      C
      quality
      D
      maintenance
      An MCP protocol server that enables web search functionality using the Tavily API, allowing AI assistants to perform internet searches in real-time.
      4
      4
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for using various search tools like Tavily API. Planning to support various search tools (i.e. wiki search, searxng, etc)
      3
      MIT