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:

1. Check environment prerequisites (Python 3.11+, Git, network connectivity)
2. Show current directory and confirm where the service will be created
3. Prompt for service name (e.g., document-processor - will create mcp-document-processor directory)
4. 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:

1. Verify environment prerequisites (Python 3.11+, Git, network)
2. Download the latest scaffold template from GitHub
3. Create a new project directory with all files configured
4. Initialize a git repository
5. 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

License

© 2025 OxSci.AI. All rights reserved.