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)--yesor-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 createmcp-document-processordirectory) - 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
EOFErrorbecause stdin is redirected. Always provide--service-nameand--tool-namewhen 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.pyfor a working example - Template Tool: See
app/tools/tool_template.pyfor 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.
