# MCP Server Template

A scaffold template for building MCP (Model Context Protocol) servers using the [oxsci-oma-mcp](https://github.com/OxSci-AI/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:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
cd mcp-{your-service-name}
```

### 1. Configure AWS CodeArtifact

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

```bash
# 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

```bash
poetry install
```

### 3. Development

#### Run Server Locally

```bash
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:**
```bash
curl http://localhost:8060/
```

**Discover available tools:**
```bash
curl http://localhost:8060/tools/discover
```

**List all tools (including disabled ones):**
```bash
curl http://localhost:8060/tools/list
```

**Execute a tool:**
```bash
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](docs/TOOL_DEVELOPMENT.md)**: 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](https://github.com/OxSci-AI/oxsci-oma-mcp): MCP protocol package
- [oxsci-oma-core](https://github.com/OxSci-AI/oxsci-oma-core): OMA agent framework
- [oxsci-shared-core](https://github.com/OxSci-AI/oxsci-shared-core): Shared utilities

## License

© 2025 OxSci.AI. All rights reserved.