oracle.oci-usage-mcp-server 1.0.0__tar.gz

oracle_oci_usage_mcp_server-1.0.0/.gitignore

@@ -0,0 +1,14 @@
+**/__pycache__/**
+
+# Virtual environment
+venv/
+.env/
+.venv/
+ENV/
+env/
+env.bak/
+venv.bak/
+
+
+# test environments
+.env

oracle_oci_usage_mcp_server-1.0.0/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.

oracle_oci_usage_mcp_server-1.0.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: oracle.oci-usage-mcp-server
+Version: 1.0.0
+Summary: OCI Usage MCP server
+Author-email: Oracle MCP <237432095+oracle-mcp@users.noreply.github.com>
+License-Expression: UPL-1.0
+License-File: LICENSE.txt
+Classifier: License :: OSI Approved :: Universal Permissive License (UPL)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.13
+Requires-Dist: fastmcp==2.12.2
+Requires-Dist: oci==2.160.0
+Description-Content-Type: text/markdown
+
+# OCI Usage MCP Server
+
+## Overview
+
+This server provides tools for interacting with Oracle Cloud Infrastructure (OCI) Usage service.
+
+## Running the server
+
+```sh
+uv run oracle.oci-usage-mcp-server
+```
+
+## Tools
+
+| Tool Name | Description |
+| --- | --- |
+| list_usage_reports | List usage reports in the tenancy |
+| get_usage_report | Get usage report by ID |
+
+⚠️ **NOTE**: All actions are performed with the permissions of the configured OCI CLI profile. We advise least-privilege IAM setup, secure credential management, safe network practices, secure logging, and warn against exposing secrets.
+
+## Third-Party APIs
+
+Developers choosing to distribute a binary implementation of this project are responsible for obtaining and providing all required licenses and copyright notices for the third-party code used in order to ensure compliance with their respective open source licenses.
+
+## Disclaimer
+
+Users are responsible for their local environment and credential safety. Different language model selections may yield different results and performance.
+
+## License
+
+Copyright (c) 2025 Oracle and/or its affiliates.
+ 
+Released under the Universal Permissive License v1.0 as shown at  
+<https://oss.oracle.com/licenses/upl/>.

oracle_oci_usage_mcp_server-1.0.0/README.md

@@ -0,0 +1,35 @@
+# OCI Usage MCP Server
+
+## Overview
+
+This server provides tools for interacting with Oracle Cloud Infrastructure (OCI) Usage service.
+
+## Running the server
+
+```sh
+uv run oracle.oci-usage-mcp-server
+```
+
+## Tools
+
+| Tool Name | Description |
+| --- | --- |
+| list_usage_reports | List usage reports in the tenancy |
+| get_usage_report | Get usage report by ID |
+
+⚠️ **NOTE**: All actions are performed with the permissions of the configured OCI CLI profile. We advise least-privilege IAM setup, secure credential management, safe network practices, secure logging, and warn against exposing secrets.
+
+## Third-Party APIs
+
+Developers choosing to distribute a binary implementation of this project are responsible for obtaining and providing all required licenses and copyright notices for the third-party code used in order to ensure compliance with their respective open source licenses.
+
+## Disclaimer
+
+Users are responsible for their local environment and credential safety. Different language model selections may yield different results and performance.
+
+## License
+
+Copyright (c) 2025 Oracle and/or its affiliates.
+ 
+Released under the Universal Permissive License v1.0 as shown at  
+<https://oss.oracle.com/licenses/upl/>.

oracle_oci_usage_mcp_server-1.0.0/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.
+"""

oracle_oci_usage_mcp_server-1.0.0/oracle/oci_usage_mcp_server/__init__.py

@@ -0,0 +1,8 @@
+"""
+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.
+"""
+
+__project__ = "oracle.oci-usage-mcp-server"
+__version__ = "1.0.0"

oracle_oci_usage_mcp_server-1.0.0/oracle/oci_usage_mcp_server/server.py

@@ -0,0 +1,102 @@
+"""
+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.
+"""
+
+import os
+from logging import Logger
+from typing import Annotated
+
+import oci
+from fastmcp import FastMCP
+from oci.usage_api.models import RequestSummarizedUsagesDetails
+
+from . import __project__, __version__
+
+logger = Logger(__name__, level="INFO")
+
+mcp = FastMCP(name=__project__)
+
+
+def get_usage_client():
+    logger.info("entering get_monitoring_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)
+    return oci.usage_api.UsageapiClient(config, signer=signer)
+
+
+@mcp.tool
+def get_summarized_usage(
+    tenant_id: Annotated[str, "Tenancy OCID"],
+    start_time: Annotated[
+        str,
+        "The value to assign to the time_usage_started property of this RequestSummarizedUsagesDetails."
+        "UTC date must have the right precision: hours, minutes, seconds, and second fractions must be 0",
+    ],
+    end_time: Annotated[
+        str,
+        "The value to assign to the time_usage_ended property of this RequestSummarizedUsagesDetails."
+        "UTC date must have the right precision: hours, minutes, seconds, and second fractions must be 0",
+    ],
+    group_by: Annotated[
+        list[str],
+        "Aggregate the result by."
+        "Allows values are “tagNamespace”, “tagKey”, “tagValue”, “service”,"
+        "“skuName”, “skuPartNumber”, “unit”, “compartmentName”, “compartmentPath”, “compartmentId”"
+        "“platform”, “region”, “logicalAd”, “resourceId”, “tenantId”, “tenantName”",
+    ],
+    compartment_depth: Annotated[float, "The compartment depth level."],
+    granularity: Annotated[
+        str,
+        'Allowed values for this property are: "HOURLY", "DAILY", "MONTHLY". Default: "DAILY"',
+    ] = "DAILY",
+    query_type: Annotated[
+        str,
+        'Allowed values are: "USAGE", "COST", "CREDIT", "EXPIREDCREDIT", "ALLCREDIT", "OVERAGE"'
+        'Default: "COST"',
+    ] = "COST",
+    is_aggregate_by_time: Annotated[
+        bool,
+        "Specifies whether aggregated by time. If isAggregateByTime is true,"
+        "all usage or cost over the query time period will be added up.",
+    ] = False,
+) -> list[dict]:
+    usage_client = get_usage_client()
+    summarized_details = RequestSummarizedUsagesDetails(
+        tenant_id=tenant_id,
+        time_usage_started=start_time,
+        time_usage_ended=end_time,
+        granularity=granularity,
+        is_aggregate_by_time=is_aggregate_by_time,
+        query_type=query_type,
+        group_by=group_by,
+        compartment_depth=compartment_depth,
+    )
+
+    response = usage_client.request_summarized_usages(
+        request_summarized_usages_details=summarized_details
+    )
+    # Convert UsageSummary objects to dictionaries for proper serialization
+    summarized_usages = [
+        oci.util.to_dict(usage_summary) for usage_summary in response.data.items
+    ]
+    return summarized_usages
+
+
+def main():
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

oracle_oci_usage_mcp_server-1.0.0/oracle/oci_usage_mcp_server/tests/test_usage_tools.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.
+"""
+
+from unittest.mock import MagicMock, create_autospec, patch
+
+import oci
+import pytest
+from fastmcp import Client
+from oracle.oci_usage_mcp_server.server import mcp
+
+
+class TestUsageTools:
+    @pytest.mark.asyncio
+    @patch("oracle.oci_usage_mcp_server.server.get_usage_client")
+    async def test_get_summarized_usage(self, mock_get_client):
+        mock_client = MagicMock()
+        mock_get_client.return_value = mock_client
+
+        mock_request_summarized_response = create_autospec(oci.response.Response)
+        mock_request_summarized_response.data = oci.usage_api.models.QueryCollection(
+            items=[
+                oci.usage_api.models.UsageSummary(
+                    compartment_id="test_compartment_id",
+                    compartment_name="test_compartment_name",
+                    computed_amount=6.731118997232,
+                    computed_quantity=69.842410393953,
+                    service="Database",
+                )
+            ]
+        )
+
+        mock_client.request_summarized_usages.return_value = (
+            mock_request_summarized_response
+        )
+        print("mock response", mock_request_summarized_response)
+        async with Client(mcp) as client:
+            result = (
+                await client.call_tool(
+                    "get_summarized_usage",
+                    {
+                        "tenant_id": "test_tenant_id",
+                        "start_time": "2023-01-01T00:00:00Z",
+                        "end_time": "2023-01-02T00:00:00Z",
+                        "group_by": ["compartment"],
+                        "compartment_depth": 1.0,
+                    },
+                )
+            ).structured_content["result"]
+
+            assert len(result) == 1
+            assert result[0]["compartment_id"] == "test_compartment_id"
+            assert result[0]["service"] == "Database"
+            assert result[0]["computed_amount"] == 6.731118997232

oracle_oci_usage_mcp_server-1.0.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "oracle.oci-usage-mcp-server"
+version = "1.0.0"
+description = "OCI Usage MCP server"
+readme = "README.md"
+license = "UPL-1.0"
+license-files = ["LICENSE.txt"]
+authors = [
+    {name = "Oracle MCP", email = "237432095+oracle-mcp@users.noreply.github.com"},
+]
+requires-python = ">=3.13"
+dependencies = [
+    "fastmcp==2.12.2",
+    "oci==2.160.0",
+]
+
+classifiers = [
+    "License :: OSI Approved :: Universal Permissive License (UPL)",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.13",
+]
+
+[project.scripts]
+"oracle.oci-usage-mcp-server" = "oracle.oci_usage_mcp_server.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["oracle"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.2",
+    "pytest-asyncio>=1.2.0",
+]