# OCI MCP Blueprint

![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)

Build, customize, package, and deploy a Python MCP server on Oracle Cloud
Infrastructure.

This repository is a blueprint for teams that want to move from a local custom
MCP server prototype to a cloud-ready service that can run on OCI Enterprise AI.
The goal is to provide both a practical reference implementation and the
supporting deployment infrastructure needed to adapt the server to real
enterprise use cases.

The project currently includes:

- a Python MCP server skeleton with a clear project structure;
- two sample MCP tools that demonstrate the expected extension points;
- centralized runtime configuration for local and cloud execution;
- tests and specifications that document the intended behaviour;
- local development instructions for running and validating the server;
- a local Agent Factory for building, publishing, and deploying the server to
  OCI Enterprise AI Hosted Applications.

## Project Scope

The blueprint focuses on a custom MCP server implemented in Python. It is meant
to be adapted by replacing or extending the sample MCP capabilities while
keeping the protocol boundary, configuration, packaging, and deployment flow
easy to understand.

The repository is intentionally scoped to:

- MCP server implementation patterns;
- sample Python code for tools, resources, and prompts;
- local validation and automated tests;
- OCI-compatible packaging and deployment;
- a factory workflow for OCI Enterprise AI deployments.

It is not intended to become a collection of unrelated agents, clients,
framework examples, or deployment targets.

## Development Model

This project follows a spec-driven development workflow. Meaningful features,
protocol changes, deployment changes, and behavioural changes should start with
a specification under `specs/` before implementation.

The first sample server design is documented in
[specs/001-sample-fastmcp-server.md](specs/001-sample-fastmcp-server.md). It
defines a Python FastMCP server with two example tools, `get_schema` and
`get_data`, backed by hard-coded fake database metadata and simulated rows.

The expected local Conda environment name is:

```bash
conda activate oci-mcp-blueprint
```

Install the package and development dependencies:

```bash
python -m pip install -e ".[dev]"
```

Optional local environment templates are documented in `.env.example`. Copy the
values you need into an ignored `.env` file or export them in your shell before
starting the local server, client, or deployment factory.

Run the sample MCP server:

```bash
python -m oci_mcp_blueprint.server
```

The server runs with FastMCP Streamable HTTP only. It binds to `0.0.0.0:8080`
and serves the MCP endpoint at `/mcp` by default.

For local-only binding:

```bash
MCP_SERVER_HOST=127.0.0.1 python -m oci_mcp_blueprint.server
```

The same entry point is available as a console script:

```bash
oci-mcp-blueprint-server
```

Test a local or remote MCP endpoint with the command-line client:

```bash
oci-mcp-blueprint-client --url http://127.0.0.1:8080/mcp list-tools
oci-mcp-blueprint-client --url http://127.0.0.1:8080/mcp get-schema
oci-mcp-blueprint-client --url http://127.0.0.1:8080/mcp get-data "status == shipped"
```

For a protected remote deployment:

```bash
oci-mcp-blueprint-client \
  --url https://example-hosted-app.example.com/mcp \
  --bearer-token "$MCP_CLIENT_BEARER_TOKEN" \
  list-tools
```

Run the project checks:

```bash
python -m black --check .
python -m pylint src tests
python -m pytest
```

Run the Docker Compose deployment:

```bash
./start_server.sh
oci-mcp-blueprint-client --url http://127.0.0.1:8080/mcp list-tools
./stop_server.sh
```

## OCI Hosted Deployment Factory

The OCI Hosted Deployment Factory is a local web application that helps you
deploy this blueprint's MCP server to OCI Enterprise AI Hosted Applications.

It is not part of the deployed MCP runtime. Instead, it is an operator tool that
runs on your workstation or jump host and guides the deployment workflow:

- collects OCI, OCIR, Hosted Application, and MCP runtime settings;
- validates inputs and OCIR credentials;
- builds the repository root `Dockerfile` as the MCP server image;
- pushes the image to OCI Container Registry;
- creates or reuses the OCI Enterprise AI Hosted Application;
- creates a Hosted Deployment from the pushed image;
- validates the hosted MCP endpoint with the standard MCP `list_tools`
  operation;
- returns the hosted MCP Streamable HTTP URL.

The factory itself has two local services:

- `agent-factory/api`: FastAPI backend for deployment orchestration.
- `agent-factory/ui`: Next.js UI for guided input and progress tracking.

The deployed runtime remains the Python FastMCP server from
`src/oci_mcp_blueprint`; it exposes Streamable HTTP at `/mcp` and does not
include the factory UI or API.

Start the factory locally:

```bash
./start_factory.sh --build
```

Then open the factory UI at:

```text
http://localhost:3100
```

The factory builds the root MCP server image, pushes it to OCIR, creates an OCI
Enterprise AI Hosted Application deployment, validates the hosted MCP endpoint
with `list_tools`, and returns the hosted `/mcp` URL. See
[docs/oci-hosted-deployment-factory.md](docs/oci-hosted-deployment-factory.md)
for details.

## Sample Tools

The server is intentionally a sample server. The schema and rows are fake,
hard-coded, deterministic data used only to demonstrate how to build a modular
MCP server.

### get_schema

Returns a structured description of the fake order-management database schema.
It supports:

- `table_name`: optional table filter;
- `include_sample_rows`: optional flag to include fake rows in the schema
  response.

### get_data

Returns simulated rows from the fake database. It accepts:

- `condition`: required demo filter expression;
- `table_name`: optional table name, default `orders`;
- `limit`: optional row limit, default `10`.

The condition is not SQL and is never executed against a database. Supported
forms are:

```text
field == value
field != value
field contains value
```

Example conditions:

```text
status == shipped
customer_name contains acme
total_amount != 0
```

## Project Layout

```text
src/oci_mcp_blueprint/
  client.py
  config.py
  server.py
  domain/
    fake_database.py
    schema_service.py
    data_service.py
  mcp/
    models.py
    tools.py
tests/unit/
specs/
agent-factory/
```

Domain logic is separated from FastMCP registration so that another MCP server
can be created by replacing the domain package and adapting the tool layer.

Runtime transport selection is intentionally not exposed. This blueprint
supports only Streamable HTTP because it targets OCI Enterprise AI hosted
deployment.

## Documentation

- [docs/customizing-mcp-server.md](docs/customizing-mcp-server.md): file-by-file
  guide for replacing the sample domain and creating a custom MCP server.
- [docs/docker-compose-deployment.md](docs/docker-compose-deployment.md): local
  Docker Compose deployment and validation guide.

## Security Notes

Do not commit secrets, private keys, API keys, OCI OCIDs, private endpoints, or
environment-specific identifiers. Runtime configuration should use environment
variables, ignored local configuration files, or documented placeholders.

The committed `.env.example` file contains only safe local defaults and empty
placeholders. Keep real tokens, passwords, OCIDs, and environment-specific URLs
in an ignored `.env` file or an external secret store.

## Current Status

The repository contains the first sample FastMCP implementation and a local
Docker Compose deployment. The next major step is the OCI Enterprise AI
deployment factory.