MCP Servers in Python

A local Programming Learning MCP Server built with FastMCP.

Description

This project exposes a small catalog of programming study topics through the Model Context Protocol (MCP). A deterministic agent-like client searches the catalog, retrieves complete topic details through MCP, and formats a short recommendation for a student. The server and client remain separate: the client starts the server as a subprocess and communicates with it over the MCP stdio transport.

Project structure:

mcp-intro/
├── server/
│   ├── learning_server.py
│   └── __init__.py
├── client/
│   ├── mcp_client.py
│   ├── agent.py
│   └── __init__.py
├── data/
│   └── topics.json
├── output/
│   └── sample_agent_response.md
├── README.md
├── requirements.txt
├── .env.example
└── .gitignore

MCP Architecture Summary

MCP is a protocol that gives AI applications a standard way to discover and use external capabilities instead of requiring a custom integration for every service.

• An MCP host is the application managing the user interaction and the overall AI experience. A host can connect to several servers, normally through one client connection per server.
• An MCP client manages one protocol connection, discovers the server's capabilities, sends tool calls or resource requests, and returns the results to the host.
• An MCP server exposes a focused set of capabilities and handles requests for them. In this project, it reads only the local topic dataset.
• A tool is an executable function with a typed input schema. For example, the agent calls search_topics with a query.
• A resource is read-only context identified by a URI. For example, topics://catalog returns the available topic ids and titles.
• A prompt is a reusable message template exposed by a server. This project does not expose prompts because they are not needed for the study lookup flow.

A server should expose only necessary capabilities. A small capability surface reduces accidental actions, limits access to data and credentials, and makes the server easier to understand and audit. Here, every exposed capability is read-only and limited to data/topics.json.

Requirements

• Python 3.10 or newer
• fastmcp==3.4.4
• python-dotenv==1.1.1

No API key, LLM account, database, or external service is required.

Setup

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

The default server path is server/learning_server.py. To override it, create .env from .env.example and change MCP_SERVER_PATH. The .env file is ignored by Git.

How to Run the Server

Start the server directly with the local stdio transport:

python server/learning_server.py

A stdio MCP server waits for protocol messages on standard input. In normal use, the client starts this process automatically, so a separate server terminal is not required.

How to Test the Server

Run the validation client:

python -m client.mcp_client

This command starts the server through MCP and verifies that:

• the server starts and completes the MCP handshake;
• search_topics and get_topic_details are discoverable;
• a valid decorators search returns results;
• a valid topic id returns complete details;
• an unknown id returns a clear error object;
• an empty query returns the message Search query must not be empty.;
• an unrelated query returns no matches;
• topics://catalog is discoverable and readable.

The tested server exposes these capability names:

Tools: search_topics, get_topic_details
Resource: topics://catalog

How to Run the Agent

Run the suggested example:

python -m client.agent "I want to study Python decorators. What should I review first?"

The program calls search_topics, selects the best result, calls get_topic_details, prints the student-facing answer, and writes it to output/sample_agent_response.md.

Use another question or output path when needed:

python -m client.agent "How do Python generators work?" --output output/generators.md

The agent never imports the server functions. client/mcp_client.py creates a FastMCP client from the server script path, which launches the server as an external subprocess and communicates through MCP over stdio.

Available Tools

search_topics

• Input: query: str
• Behavior: performs deterministic, case-insensitive matching against topic ids, titles, summaries, and key concepts.
• Output: up to five ranked matches containing id, title, summary, and key_concepts.
• No match: returns an empty list.
• Invalid input: an empty query produces a clear MCP tool error.
• Side effects: none; the tool is marked read-only and closed-world.

get_topic_details

• Input: topic_id: str
• Behavior: performs an exact, case-insensitive id lookup.
• Output: the full topic object, including prerequisites, key concepts, common mistakes, and a practice idea.
• Unknown id: returns an object containing a clear error message.
• Side effects: none; the tool is marked read-only and closed-world.

Available Resources

topics://catalog

A read-only application/json resource containing only the available topic ids and titles. It is intended for browsing and does not modify the dataset.

Example shape:

[
  {"id": "python-functions", "title": "Python Functions"},
  {"id": "python-decorators", "title": "Python Decorators"}
]

Third-Party MCP Server Review

The reviewed third-party server is the official GitHub MCP Server. The review was based on its repository documentation; it was not installed and no credentials were provided.

• Purpose: connects MCP hosts to GitHub so an agent can inspect repositories and code, work with issues and pull requests, examine Actions, and access other GitHub features.
• Location: it can run remotely as a GitHub-hosted HTTP server or locally as a Docker container/native Go binary using stdio.
• Capabilities: configurable toolsets include context, repos, issues, pull_requests, actions, code_security, and others. Example tools include get_me, repository content lookup, issue operations, pull-request operations, and Actions inspection or triggering. The default toolsets are context, repos, issues, pull_requests, and users.
• Permissions and credentials: remote use supports OAuth or a GitHub Personal Access Token. Local use supports OAuth or GITHUB_PERSONAL_ACCESS_TOKEN. Available operations depend on token scopes such as repository access, read:org, or security_events.
• Risk: a broadly scoped token combined with write tools could let an agent expose private repository data or modify issues, pull requests, workflows, or other GitHub state.
• Safety measure: use the documented read-only mode, allow only the required tools or toolsets, and provide a fine-grained token limited to a disposable test repository. The server source/image, requested scopes, configuration, and tool list should be reviewed before each use, and credentials must never be committed.

Example Output

The complete generated response is stored in output/sample_agent_response.md.

# Study Recommendation

**Question:** I want to study Python decorators. What should I review first?

## Recommended Topic: Python Decorators

**Why it is relevant:** Decorators wrap callables to extend their behavior without changing their original implementation.

## Review First

- Python functions
- Local and enclosing scope
- Functions as first-class objects

Known Limitations

• The catalog is a small static JSON file and must be edited manually.
• Search is keyword-based and does not understand synonyms or semantic meaning.
• The deterministic agent always selects the first ranked result and does not ask clarifying questions.
• The implementation uses local stdio; it does not provide authentication, multi-user isolation, or remote deployment.
• No LLM is used, so response wording follows a fixed Markdown template.
• Dataset validation checks required fields but does not deeply validate every field's value type.

Reflection

What problem does MCP solve?

MCP replaces many one-off agent integrations with one protocol for capability discovery and structured communication. A compatible client can use different servers without directly importing their implementation code.

What is the difference between an MCP tool and an MCP resource?

A tool is called with arguments to execute a server-side function. A resource is read through a URI and provides read-only context. This project uses tools for search and exact lookup, while the compact catalog is a resource.

What does this MCP server expose?

It exposes the search_topics and get_topic_details tools plus the topics://catalog resource. All three capabilities read the local programming topic dataset without modifying it.

How does the agent use the MCP server?

The agent-like application creates an MCP client that launches the server as a subprocess. It calls search_topics with the student's question, calls get_topic_details with the selected id, and formats only the returned MCP data into a recommendation.

What should be checked before using a third-party MCP server?

Its publisher and source, local or remote execution model, exposed tools and resources, network and filesystem access, required scopes, credential storage, write or destructive operations, update policy, and whether its access can be restricted to the minimum needed.

What limitation was observed in this implementation?

Keyword ranking works for the included examples but cannot infer semantic relationships. A differently worded question may miss a relevant topic or rank a generic Python topic too highly.