MCP Server Template

A scaffold template for building MCP (Model Context Protocol) servers using the oxsci-oma-mcp framework.

Prerequisites

Python 3.11 or higher
Poetry for dependency management
AWS CLI configured with access to CodeArtifact (for installing dependencies from CodeArtifact)

Note: Docker is only required for CI/CD deployment workflows, not for local development.

Installation

Installation Prerequisites

The installer script itself only requires Python 3.11+ (uses only Python standard library, no external packages needed).

However, to complete the installation, you also need:

Git installed (for initializing the repository)
Network connectivity to GitHub (for downloading the template)
Write permissions in the directory where you'll run the script

The installer will also check for:

AWS CLI (warning only - required later for CodeArtifact access, but not needed during installation)

The installer will automatically check these prerequisites before proceeding.

Option 1: Quick Install (Recommended)

Install directly from GitHub with a single command. You can use either command-line arguments (recommended) or interactive prompts.

Important: Run the script from the parent directory where you want to create the service. For example:
To create /git/mcp-my-service/, run the script from /git/ directory
The script will create mcp-{service-name}/ in the current working directory

Direct Installation with Arguments (Recommended)

The simplest way - directly download and execute with parameters:

# Navigate to the parent directory where you want to create the service cd /git # Run the installer curl -sSL https://raw.githubusercontent.com/OxSci-AI/oxsci-mcp-scaffold/main/install.py | python3 - \ --service-name document-processor \ --tool-name document_processor \ --yes

Command-line options:

--service-name: Service name (must start with a letter, lowercase letters/numbers/hyphens only)
--tool-name: Initial tool name (must start with a letter, lowercase letters/numbers/underscores only)
--yes or -y: Skip confirmation prompt (recommended for non-interactive mode)
--skip-env-check: Skip environment prerequisites check (not recommended)

Interactive Mode

If you prefer to answer prompts interactively, download the script first:

# Navigate to the parent directory where you want to create the service cd /git # Download and run interactively curl -sSL https://raw.githubusercontent.com/OxSci-AI/oxsci-mcp-scaffold/main/install.py > install.py python3 install.py

The script will:

Check environment prerequisites (Python 3.11+, Git, network connectivity)
Show current directory and confirm where the service will be created
Prompt for service name (e.g., document-processor - will create mcp-document-processor directory)
Prompt for tool name (e.g., document_processor - will create the initial tool file and configure it)

Note: If you try to use the pipe method without arguments, you'll get an EOFError because stdin is redirected. Always provide --service-name and --tool-name when using the pipe method.

The installer will:

Verify environment prerequisites (Python 3.11+, Git, network)
Download the latest scaffold template from GitHub
Create a new project directory with all files configured
Initialize a git repository
Set up the tool structure and configuration files

Option 2: Manual Setup

If you prefer to clone the repository first:

# Clone the repository git clone https://github.com/OxSci-AI/oxsci-mcp-scaffold.git cd oxsci-mcp-scaffold # Run setup script python setup.py

The setup script will prompt you for:

Service name (will create mcp-{service-name} directory)
Tool name (will create the initial tool file and configure it)

Quick Start

After installation, navigate to your new service directory:

cd mcp-{your-service-name}

1. Configure AWS CodeArtifact

Before installing dependencies, configure access to the private package repository:

# Make the script executable (if not already) chmod +x entrypoint-dev.sh # Run the configuration script (valid for 12 hours) ./entrypoint-dev.sh

Note: The authentication token expires after 12 hours. Re-run this script when needed.

2. Install Dependencies

poetry install

3. Development

Run Server Locally

poetry run uvicorn app.core.main:app --reload --port 8060

Access the server at: http://localhost:8060

API documentation: http://localhost:8060/docs
Tool discovery: http://localhost:8060/tools/discover
Tool list: http://localhost:8060/tools/list

Test Your Tools

Check server status:

curl http://localhost:8060/

Discover available tools:

curl http://localhost:8060/tools/discover

List all tools (including disabled ones):

curl http://localhost:8060/tools/list

Execute a tool:

curl -X POST http://localhost:8060/tools/example_tool \ -H "Content-Type: application/json" \ -d '{ "arguments": { "input_text": "Hello World", "uppercase": true }, "context": { "user_id": "user123" } }'

Project Structure

mcp-{service-name}/ ├── .github/ │ └── workflows/ │ └── docker-builder.yml # CI/CD workflow for building and deploying ├── app/ │ ├── core/ │ │ ├── __init__.py │ │ ├── config.py # Service configuration │ │ └── main.py # FastAPI application entry point │ └── tools/ │ ├── __init__.py # Import tools here │ ├── example_tool.py # Example tool implementation │ └── tool_template.py # Comprehensive tool template (disabled) ├── docs/ │ └── TOOL_DEVELOPMENT.md # Tool development guide ├── tests/ │ └── test_example.py # Example tests ├── .vscode/ │ └── extensions.json # Recommended VS Code extensions ├── Dockerfile # Multi-stage Docker build ├── entrypoint-dev.sh # CodeArtifact configuration script ├── install.py # Installer script (for creating new services) ├── setup.py # Setup script (for local setup) ├── pyproject.toml # Project dependencies and configuration └── README.md # This file

Next Steps

Once your service is set up and running, refer to these resources:

Tool Development Guide: Learn how to create, configure, and deploy MCP tools
API Documentation: Visit http://localhost:8060/docs when running locally
Example Tool: Check app/tools/example_tool.py for a working example
Template Tool: See app/tools/tool_template.py for comprehensive patterns

Tools and Frameworks

This template integrates:

FastAPI: Web framework for building APIs
oxsci-oma-mcp: MCP protocol implementation and tool router
oxsci-shared-core: Shared utilities and configuration (optional)

Related Projects

oxsci-oma-mcp: MCP protocol package
oxsci-oma-core: OMA agent framework
oxsci-shared-core: Shared utilities

MCP Server Template

MCP Server Template

Prerequisites

Installation

Installation Prerequisites

Option 1: Quick Install (Recommended)

Direct Installation with Arguments (Recommended)

Interactive Mode

Option 2: Manual Setup

Quick Start

1. Configure AWS CodeArtifact

2. Install Dependencies

3. Development

Run Server Locally

Test Your Tools

Project Structure

Next Steps

Tools and Frameworks

Related Projects

License

Related Resources

New MCP Servers

MCP directory API