Python MCP Server

A beginner-friendly MCP server built in Python that helps AI agents find shared solutions for Coding Challenges.

Built by following: Build Your Own MCP Server for AI Agents.

MCP (Model Context Protocol) is an open standard for connecting AI agents to external tools and data sources. This server exposes Python functions as MCP tools that any compatible agent or inspector can call.

Demo Output (Inspector)

Available Tools

Tool	Input	What it does
hello	name	Returns Hello, <name>. Smoke test for connectivity.
coding_challenge_solution_finder	challenge_name	Searches the SharedSolutions repo and returns matching challenge pages.
coding_challenge_solutions_by_language	challenge_name, language	Same as above, filtered to a specific programming language.

Requirements

• Python 3.10 or newer
• Node.js (only needed to run MCP Inspector)

Setup

Clone the repo and create a virtual environment.

# Windows
git clone https://github.com/YOUR_USERNAME/python-mcp-server.git
cd python-mcp-server
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

# macOS / Linux
git clone https://github.com/YOUR_USERNAME/python-mcp-server.git
cd python-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run the Server

The server communicates over stdio (standard input/output). It has no visible output while idle — this is normal for MCP stdio servers.

# Windows
.venv\Scripts\python.exe server.py

# macOS / Linux
.venv/bin/python server.py

Press Ctrl+C to stop.

Test with MCP Inspector

MCP Inspector is a browser-based tool for interacting with your server.

# Windows
npx -y @modelcontextprotocol/inspector .venv\Scripts\python.exe server.py

# macOS / Linux
npx -y @modelcontextprotocol/inspector .venv/bin/python server.py

Then in the Inspector UI:

1. Click Connect
2. Click List Tools
3. Click a tool name and enter input
4. Click Run Tool

Sample Inputs

hello

{ "name": "world" }

Expected output: Hello, world

coding_challenge_solution_finder

{ "challenge_name": "wc" }

Expected output: a list of matching challenge page links.

coding_challenge_solutions_by_language

{ "challenge_name": "wc", "language": "Python" }

Expected output: a filtered list of solutions written in Python.

Run the Tests

# Windows
.venv\Scripts\python.exe -m unittest discover -s tests -v

# macOS / Linux
.venv/bin/python -m unittest discover -s tests -v

Error Codes

Tools return a structured dictionary if something goes wrong:

Code	Meaning
INVALID_INPUT	Input was empty or missing
GITHUB_UNAVAILABLE	Network error reaching GitHub
FETCH_FAILED	GitHub responded with a non-200 status
README_FORMAT_CHANGED	The upstream README has no parseable links
CHALLENGE_NOT_FOUND	No challenge matched the given name
NO_LANGUAGE_MATCH	Challenge found but no rows for that language

Project Structure

python-mcp-server/
  server.py                    # app entrypoint and tool registration
  tools/
    hello_tool.py              # hello tool
    challenge_finder_tool.py   # solution finder tool
    language_filter_tool.py    # language filter tool
  services/
    shared_solutions.py        # shared GitHub fetch and markdown parsing
  tests/
    test_shared_solutions_placeholder.py
  notes/                       # learning notes and troubleshooting
  requirements.txt
  LICENSE

How It Works

1. server.py creates the FastMCP app and registers tool functions.
2. Each tool lives in its own file under tools/.
3. Shared logic (fetching README, parsing tables) lives in services/.
4. When a tool is called, it fetches live data from the CodingChallengesFYI/SharedSolutions GitHub repository.

Learning Notes

Extra notes covering MCP concepts and troubleshooting:

• What is MCP Inspector
• MCP Server Basics
• MCP Tool Design
• stdio vs HTTP transport
• Inspector startup and debugging
• Python-first testing alternatives
• Connecting MCP to agents
• Portfolio demo script

Improvement Ideas

1. Add strict language matching (so java does not also match JavaScript).
2. Expand test coverage for services/shared_solutions.py.
3. Add caching to avoid repeated README downloads.

License

MIT — 2026 msjackiebrown