aitour26-LTG152-from-protocol-to-practice-build-and-use-your-first

This repository provides a minimal Python MCP server that demonstrates how an MCP server can host tools and resources and expose them to MCP clients. The server uses a CSV ledger to record simple read/write operations as part of its example tooling, allowing you to validate end-to-end interactions with an MCP client or inspector. After starting the server, you can connect with an MCP Inspector or a client that speaks the MCP protocol to browse available prompts, tools, and resources, then invoke a tool to read from or write to the CSV ledger. The example focuses on a lightweight, easy-to-understand workflow suitable for learning MCP basics and validating protocol logic.

Once running, you’ll typically see endpoints or prompts exposed by the server that map to simple actions (for example, appending a row to the ledger or querying ledger contents). Tools are described in the server’s tool definitions and are discoverable by MCP clients. You can use the MCP Inspector to validate prompts, test tool invocations, and inspect the resulting ledger updates in real time. This setup is ideal for hands-on experimentation with protocol exchanges, client-tool orchestration, and basic resource retrieval.

Prerequisites

• Python 3.12 or compatible interpreter
• Basic command-line experience

Step-by-step installation

1. Install Python 3.12 from the official Python website or your OS package manager.
2. Create a virtual environment:
   • macOS/Linux: python3 -m venv venv
   • Windows: python -m venv venv
3. Activate the virtual environment:
   • macOS/Linux: source venv/bin/activate
   • Windows: .\venv\Scripts\activate.bat
4. Install the MCP server package (example name used by this project):
   • pip install fastmcp
5. Run the MCP server:
   • python -m fastmcp
6. (Optional) Customize ledger path via environment variable or config if needed:
   • export MCP_LEDGER=./ledger.csv
   • Windows: set MCP_LEDGER=./ledger.csv

Notes

• If you prefer to run via uvx, you can adapt the command to your environment by installing the package and running it through uvx, but this guide uses the Python module approach as demonstrated by the repository.

Tips and common issues:

• Ensure Python 3.12 is installed and active in your PATH before creating the virtual environment.
• If the ledger file doesn’t exist, the server should create it automatically; if not, verify filesystem permissions.
• The MCP Inspector is a useful companion tool to validate prompts, see available tools, and simulate client interactions.
• If you need to expose the server to other devices, run with appropriate host/port configuration and ensure network accessibility.
• Review any environment variables used by the server (for example, MCP_LEDGER) and set defaults if you plan to commit to source control.
• For troubleshooting, inspect the console output for startup messages, errors related to missing dependencies, or ledger write permissions.

Environment variables to be aware of:

• MCP_LEDGER: Path to the CSV ledger file used for read/write demonstrations.
• LOG_LEVEL: Logging verbosity (e.g., DEBUG, INFO, WARNING).

Configuration options:

• The server can be extended with additional tools or prompts; refer to the project docs for adding new MCP tools and wiring them to the ledger.