Add MCP Server Template

.gitignore

@@ -1,3 +1,5 @@
 **/.env
 **/.venv
 **/.langgraph_api/
+
+.idea

README.md

@@ -10,6 +10,7 @@ Prototypes and proofs-of-concept
 | [policy](./policy) | Demonstration of out-of-band policy enforcement for MCP servers/tools |
 | [server](./server) | Example of MCP authentication using OCI IDCS and OAuth |
 | [infrastructure](./infrastructure) | Example templates that instantiate an OCI GPU compute instance and install the Nvidia stack |
+| [generator](./generator) | A utility to quickly generate an OCI-specific MCP server using [cookiecutter](https://cookiecutter.readthedocs.io/en/stable/) |
 
 ## Getting started
 
@@ -38,4 +39,4 @@ Developers choosing to distribute a binary implementation of this project are re
 
 ## Disclaimer
 
-Users are responsible for their local environment and credential safety. Different language model selections may yield different results and performance.
+Users are responsible for their local environment and credential safety. Different language model selections may yield different results and performance.

generator/README.md

@@ -0,0 +1,62 @@
+# OCI MCP Server Generator
+
+This directory contains a Cookiecutter template for generating OCI MCP servers.
+
+## Prerequisites
+
+- Python 3.9 or higher
+- UV (`brew install uv`)
+- Cookiecutter (`pip install cookiecutter`)
+
+## Usage
+
+1. If you want to use the existing cookiecutter template in another project like the [Oracle MCP](https://github.com/oracle/mcp), run the below command. You may need to change the `output-dir`
+   ```
+   uvx cookiecutter https://github.com/oracle-samples/mcp-examples.git --directory generator --output-dir ./src 
+   ```
+
+2. Follow the prompts to enter the required information
+3. Cookiecutter will generate a new directory with your MCP server project.
+
+## Testing
+
+1. If you want to test the project template, run the below command
+   ```
+   uvx cookiecutter generator
+   ```
+2. Following the prompts and it will generator a directory with your MCP servers.
+3. Adjust the files within the `generator` folder to modify the output
+4. For dynamic variables or advanced usage, see the [official readme](https://cookiecutter.readthedocs.io/en/stable/README.html)
+5. Do not commit generated code to this repository
+
+## Generated Project Structure
+
+Here's an example of the directory structure generated by this template when using "test" as the project_domain:
+
+```
+oci-test-mcp-server/
+├── .gitignore
+├── .python-version
+├── CHANGELOG.md
+├── LICENSE.txt
+├── pyproject.toml
+├── README.md
+├── uv-requirements.txt
+└── oracle/
+    ├── __init__.py
+    └── oci_test_mcp_server/
+        ├── __init__.py
+        ├── server.py
+        └── tests/
+```
+
+## Template Variables
+
+- `project_domain`: Used to generate the project directory name and other identifiers.
+- `description`: Used to generate a description of the project.
+- `instructions`: "Instructions for using this MCP server.
+
+## Notes
+
+- The generated MCP server project includes basic configuration and structure. You will need to modify and extend it according to your specific requirements.
+- Refer to the [Cookiecutter documentation](https://cookiecutter.readthedocs.io/) for more advanced usage and customization options.

generator/cookiecutter.json

@@ -0,0 +1,8 @@
+{
+  "_copy_without_render": [
+    ".gitignore"
+  ],
+  "project_domain": "This is the domain of your service. It will be used to generate folders in the structure of 'oracle.oci-{project_domain}-mcp-server'",
+  "description": "An OCI Model Context Protocol server for {{ cookiecutter.project_domain }}",
+  "instructions": "Instructions for using this {{ cookiecutter.project_domain }} MCP server. This can be used by clients to improve the LLM's understanding of available tools, resources, etc. It can be thought of like a 'hint' to the model. For example, this information MAY be added to the system prompt. Important to be clear, direct, and detailed."
+}

generator/oci-{{cookiecutter.project_domain | lower | replace(' ', '-') | replace('_', '-')}}-mcp-server/.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv
+env/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.tox/
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+
+# Ruff
+.ruff_cache/
+
+# Build
+*.manifest
+*.spec
+.pybuilder/
+target/
+
+# Environments
+.env
+.env.local
+.env.*.local
+
+# PyPI
+.pypirc

generator/oci-{{cookiecutter.project_domain | lower | replace(' ', '-') | replace('_', '-')}}-mcp-server/.python-version

@@ -0,0 +1 @@
+3.13

generator/oci-{{cookiecutter.project_domain | lower | replace(' ', '-') | replace('_', '-')}}-mcp-server/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+### Added
+
+- Initial project setup

generator/oci-{{cookiecutter.project_domain | lower | replace(' ', '-') | replace('_', '-')}}-mcp-server/LICENSE.txt

@@ -0,0 +1,35 @@
+Copyright (c) 2025 Oracle and/or its affiliates.
+
+The Universal Permissive License (UPL), Version 1.0
+
+Subject to the condition set forth below, permission is hereby granted to any
+person obtaining a copy of this software, associated documentation and/or data
+(collectively the "Software"), free of charge and under any and all copyright
+rights in the Software, and any and all patent rights owned or freely
+licensable by each licensor hereunder covering either (i) the unmodified
+Software as contributed to or provided by such licensor, or (ii) the Larger
+Works (as defined below), to deal in both
+
+(a) the Software, and
+(b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+one is included with the Software (each a "Larger Work" to which the Software
+is contributed by such licensors),
+
+without restriction, including without limitation the rights to copy, create
+derivative works of, display, perform, and distribute the Software and make,
+use, sell, offer for sale, import, export, have made, and have sold the
+Software and the Larger Work(s), and to sublicense the foregoing rights on
+either these or other terms.
+
+This license is subject to the following condition:
+The above copyright notice and either this complete permission notice or at
+a minimum a reference to the UPL must be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

generator/oci-{{cookiecutter.project_domain | lower | replace(' ', '-') | replace('_', '-')}}-mcp-server/README.md

@@ -0,0 +1,16 @@
+# OCI {{cookiecutter.project_domain}} MCP Server
+
+{{cookiecutter.description}}
+
+## Instructions
+
+{{cookiecutter.instructions}}
+
+## TODO (REMOVE AFTER COMPLETING)
+
+* [ ] Generate a `uv.lock` file with `uv sync` -> See [Getting Started](https://docs.astral.sh/uv/getting-started/)
+* [ ] Remove the example tools in `./oracle/oci-{{cookiecutter.project_domain | lower | replace(' ', '-') | replace('_', '-') | replace('-', '_')}}_mcp_server/server.py`
+* [ ] Add your own tool(s)
+* [ ] Keep test coverage at or above the `main` branch
+* [ ] Document the MCP Server in this "README.md"
+* [ ] Submit a PR and pass all the checks

generator/oci-{{cookiecutter.project_domain | lower | replace(' ', '-') | replace('_', '-')}}-mcp-server/oracle/__init__.py

@@ -0,0 +1,5 @@
+"""
+Copyright (c) 2025, Oracle and/or its affiliates.
+Licensed under the Universal Permissive License v1.0 as shown at
+https://oss.oracle.com/licenses/upl.
+"""

generator/oci-{{cookiecutter.project_domain | lower | replace(' ', '-') | replace('_', '-')}}-mcp-server/oracle/oci_{{cookiecutter.project_domain | lower | replace(' ', '_') | replace('-', '_')}}_mcp_server/__init__.py

@@ -0,0 +1,10 @@
+"""
+Copyright (c) 2025, Oracle and/or its affiliates.
+Licensed under the Universal Permissive License v1.0 as shown at
+https://oss.oracle.com/licenses/upl.
+"""
+
+"""oracle.oci-{{cookiecutter.project_domain | lower | replace(' ', '-') | replace('_', '-')}}-mcp-server"""
+
+__version__ = '0.0.0'
+__project__ = "oracle.oci-{{cookiecutter.project_domain | lower | replace(' ', '-') | replace('_', '-')}}-mcp-server"

generator/oci-{{cookiecutter.project_domain | lower | replace(' ', '-') | replace('_', '-')}}-mcp-server/oracle/oci_{{cookiecutter.project_domain | lower | replace(' ', '_') | replace('-', '_')}}_mcp_server/server.py

@@ -0,0 +1,56 @@
+"""
+Copyright (c) 2025, Oracle and/or its affiliates.
+Licensed under the Universal Permissive License v1.0 as shown at
+https://oss.oracle.com/licenses/upl.
+"""
+
+"""oracle oci-{{cookiecutter.project_domain}} MCP Server implementation."""
+
+import os
+import oci
+
+from logging import Logger
+from mcp.server.fastmcp import FastMCP
+
+
+from . import __project__, __version__
+
+logger = Logger(__name__, level="INFO")
+
+mcp = FastMCP(name=__project__, instructions='{{cookiecutter.instructions | replace('\'', '\'\'')}}')
+
+def get_{{cookiecutter.project_domain}}_client():
+    config = oci.config.from_file(
+        profile_name=os.getenv("OCI_CONFIG_PROFILE", oci.config.DEFAULT_PROFILE)
+    )
+    user_agent_name = __project__.split("oracle.", 1)[1].split("-server", 1)[0]
+    config["additional_user_agent"] = f"{user_agent_name}/{__version__}"
+    private_key = oci.signer.load_private_key_from_file(config["key_file"])
+    token_file = config["security_token_file"]
+    token = None
+    with open(token_file, "r") as f:
+        token = f.read()
+    signer = oci.auth.signers.SecurityTokenSigner(token, private_key)
+    # Update this line to return the correct client
+    return oci.core.{{cookiecutter.project_domain.capitalize()}}Client(config, signer=signer)
+
+@mcp.tool(name='ExampleTool')
+async def example_tool(
+    query: str,
+) -> str:
+    """Example tool implementation.
+
+    Replace this with your own tool implementation.
+    """
+    project_name = 'oracle {{cookiecutter.project_domain}} MCP Server'
+    return (
+        f"Hello from {project_name}! Your query was {query}. Replace this with your tool's logic"
+    )
+
+def main():
+    """Run the MCP server with CLI argument support."""
+    mcp.run()
+
+
+if __name__ == '__main__':
+    main()

generator/oci-{{cookiecutter.project_domain | lower | replace(' ', '-') | replace('_', '-')}}-mcp-server/oracle/oci_{{cookiecutter.project_domain | lower | replace(' ', '_') | replace('-', '_')}}_mcp_server/tests/test_{{cookiecutter.project_domain | lower | replace(' ', '_') | replace('-', '_')}}_tools.py

@@ -0,0 +1,30 @@
+"""
+Copyright (c) 2025, Oracle and/or its affiliates.
+Licensed under the Universal Permissive License v1.0 as shown at
+https://oss.oracle.com/licenses/upl.
+"""
+
+
+"""Tests for the oci-{{cookiecutter.project_domain}} MCP Server."""
+from unittest.mock import MagicMock, create_autospec, patch
+
+import oci
+import pytest
+from fastmcp import Client
+from oracle.oci-{{cookiecutter.project_domain | lower | replace(' ', '_') | replace('-', '_')}}-mcp-server.server import mcp
+
+
+class Test{{cookiecutter.project_domain | lower | replace(' ', '') | replace('-', '') | replace('_', '')}}Tools:
+    @pytest.mark.asyncio
+    @pytest.mark.skip(reason="Not implemented")
+    def test_example_tool():
+        # Arrange
+        test_query = "test query"
+        expected_project_name = "oracle oci-{{cookiecutter.project_domain}} MCP Server"
+        expected_response = f"Hello from {expected_project_name}! Your query was {test_query}. Replace this with your tool's logic"
+
+        # Act
+        result = await example_tool(test_query)
+
+        # Assert
+        assert result == expected_response

generator/oci-{{cookiecutter.project_domain | lower | replace(' ', '-') | replace('_', '-')}}-mcp-server/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "oracle.oci-{{cookiecutter.project_domain | lower | replace(' ', '-') | replace('_', '-')}}-mcp-server"
+
+version = "0.0.0"
+description = "{{cookiecutter.description}}"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "fastmcp==2.12.2",
+    "oci==2.160.0",
+    "pydantic==2.12.3",
+]
+license = "UPL-1.0"
+license-files = ["LICENSE.txt"]
+authors = [
+    {name = "Oracle MCP", email = "[email protected]"},
+]
+
+classifiers = [
+    "License :: OSI Approved :: Universal Permissive License (UPL)",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.13",
+]
+
+[project.scripts]
+"oracle.oci-{{cookiecutter.project_domain | lower | replace(' ', '-') | replace('_', '-')}}-mcp-server" = "oracle.oci_{{cookiecutter.project_domain | lower | replace(' ', '_') | replace('-', '_')}}_mcp_server.server:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.2",
+    "pytest-asyncio>=1.2.0",
+    "pytest-cov>=7.0.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["oracle"]
+
+[tool.coverage.run]
+omit = [
+    "**/__init__.py",
+    "**/tests/*",
+    "dist/*",
+    ".venv/*",
+]
+
+[tool.coverage.report]
+omit = [
+    "**/__init__.py",
+    "**/tests/*",
+]
+precision = 2
+fail_under = 90