neilpeterson/mcp-infra-scaffold

Template Server - A Simple MCP Server

This is a simple Model Context Protocol (MCP) server implementation that provides tools for working with various file formats, including CSV, Parquet, JSON, YAML, and Bicep. This project is based on the Building a Basic MCP Server with Python tutorial.

Overview

This MCP server provides tools that allow AI models like Claude to interact with various file formats, retrieving summaries about their structure. The server is built using Python and the FastMCP server implementation. It enables AI assistants to analyze:

• CSV and Parquet files (rows and columns count)
• JSON structures (keys for objects, count for arrays)
• YAML configurations (keys for mappings, count for sequences)
• Bicep templates for Azure (resources, parameters, variables, outputs)

Project Structure

/
├── main.py              # Entry point for running the server
├── server.py            # FastMCP server configuration 
├── requirements.txt     # Project dependencies
├── mcp.bicep            # Bicep template for Azure resources
├── data/                # Directory for data files
│   ├── sample.csv       # Sample CSV file for testing
│   ├── sample.parquet   # Sample Parquet file for testing
│   ├── json/            # JSON files directory
│   │   └── sample.json  # Sample JSON file for testing
│   ├── yaml/            # YAML files directory
│   │   └── sample.yaml  # Sample YAML file for testing
│   └── bicep/           # Bicep files directory
│       └── main.bicep   # Sample Bicep file for testing
├── tools/               # MCP tools implementation
│   ├── csv_tools.py     # Tools for working with CSV files
│   ├── parquet_tools.py # Tools for working with Parquet files
│   ├── json_tools.py    # Tools for working with JSON files
│   ├── yaml_tools.py    # Tools for working with YAML files
│   ├── bicep_tools.py   # Tools for working with Bicep files
│   └── file_tools.py    # Tools for reading file contents
└── utils/               # Utility functions
    └── file_reader.py   # Utilities for reading files

Dependencies

This project requires the following dependencies:

• Python 3.11 or higher
• MCP library with CLI support
• Pandas for data manipulation
• PyArrow for Parquet file support
• PyYAML for YAML file support

All dependencies are listed in the requirements.txt file.

Installation

1. Clone this repository
2. Navigate to the project directory
3. Install dependencies using pip:

pip install -r requirements.txt

Virtual Environment Management

You can use a virtual environment to isolate the project dependencies:

# Create a new environment
python -m venv .venv

# Activate the environment (PowerShell)
.venv/bin/Activate.ps1

# Install dependencies from requirements.txt
pip install -r requirements.txt

Running the Server

To run the MCP server:

python main.py

For PowerShell users:

python ./main.py

VS Code Setup

To configure VS Code for development with this project:

1. Install the Python extension for VS Code
2. Create a .vscode folder at the root of the project
3. Create a settings.json file with the following configuration:

{
    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
    "python.linting.enabled": true,
    "python.linting.pylintEnabled": true,
    "python.formatting.provider": "black",
    "editor.formatOnSave": true,
    "python.analysis.extraPaths": [
        "${workspaceFolder}"
    ]
}

4. Create a launch.json file for debugging:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: MCP Server",
            "type": "python",
            "request": "launch",
            "program": "${workspaceFolder}/main.py",
            "console": "integratedTerminal",
            "justMyCode": false,
            "env": {
                "PYTHONPATH": "${workspaceFolder}"
            }
        }
    ]
}

This setup allows you to run and debug the MCP server directly from VS Code using the integrated terminal and debugger.

Available Tools

CSV Tools

• summarize_csv_file: Takes a filename parameter and returns a summary of the CSV file's structure (number of rows and columns).

Parquet Tools

• summarize_parquet_file: Takes a filename parameter and returns a summary of the Parquet file's structure (number of rows and columns).

JSON Tools

• summarize_json_file: Takes a filename parameter and returns a summary of the JSON file's structure (keys for objects, count for arrays).

YAML Tools

• summarize_yaml_file: Takes a filename parameter and returns a summary of the YAML file's structure (keys for mappings, count for sequences).

Bicep Tools

• summarize_bicep_file: Takes a filename parameter and returns a summary of the Bicep file's contents (counts of resources, parameters, variables, and outputs).

File Reading Tools

• read_file_contents: Takes a filename parameter and returns the complete contents of any file in the data directory. Paths can include subdirectories, e.g., 'json/config.json', 'bicep/main.bicep'.

Configuring with Claude Desktop

To use this MCP server with Claude Desktop, add the following configuration to your Claude Desktop config file (located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "template_server": {
      "command": "python",
      "args": [
        "/Users/neilpeterson/Documents/code/personal-projects-and-ramp/mcp-infra-scaffold/main.py"
      ]
    }
  }
}

Alternatively, if you're using a virtual environment:

{
  "mcpServers": {
    "template_server": {
      "command": "pwsh",
      "args": [
        "-Command",
        "& {cd '/Users/neilpeterson/Documents/code/personal-projects-and-ramp/mcp-infra-scaffold'; python ./main.py}"
      ]
    }
  }
}

Example Usage

Once connected to an AI assistant like Claude, you can use the tools to analyze data files:

Please summarize the sample CSV file in the data directory.

The AI will invoke the summarize_csv_file tool to provide information about the file.

You can also work with other file types:

Can you analyze the structure of sample.json?

The AI will use the summarize_json_file tool to provide details about the JSON structure.

What resources are defined in the Bicep template?

The AI will use the summarize_bicep_file tool to provide information about the resources, parameters, variables, and outputs in the Bicep file (e.g., main.bicep).

Show me the contents of the sample.yaml file.

The AI will use the read_file_contents tool to display the full contents of the YAML file.

Extending the Server

To add new tools, create new Python modules in the tools directory and import them in main.py. Use the @mcp.tool() decorator to register new functions as tools.