342 fixes

src/oci-db-observability-mcp-server/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+## Unreleased
+
+### Tool surface
+
+- Clarified `list_jobs` sorting guidance so ordinary inventory requests omit
+  optional sorting, while retaining the OCI SDK's documented sort values.
+- Added the `database-and-infra-observability-metric-catalog` skill with local
+  metric catalog search/get/list handlers, a catalog-validated live OCI
+  Monitoring metric reader, and read-only OCI Monitoring alarm definition and
+  status operations.
+- Added capability-first classification, AWR fallback, and single-target
+  validation checkpoints to health and AWR skill prompts.
+
+## 0.1.0 - 2026-08-05
+
+### Server
+
+- Unified, read-only Oracle Database Observability MCP server for OCI
+  Operations Insights (OPSI) and Database Management (DBM).
+
+### Transports
+
+- STDIO and HTTP streaming transports.
+
+### Authentication
+
+- Configured OCI authentication through `oracle-mcp-common`, including
+  API-key, security-token, instance-principal, and resource-principal flows.
+- OCI IAM/IDCS request-token authentication for HTTP deployments.
+
+### Tool surface
+
+- Explicit-compartment scope discovery through `get_oci_compartment` and
+  `list_oci_compartments`.
+- Catalog discovery and dispatch through `list_dbo_skills`, `list_dbo_tools`,
+  `describe_dbo_tool`, and `invoke_dbo_tool`.
+- 34 workflow skills and 229 read-only OPSI/DBM SDK-backed catalog operations.
+
+### Package and entry point
+
+- Distribution: `oracle.oci-db-observability-mcp-server`.
+- Console entry point: `oracle.oci-db-observability-mcp-server`.
+- Python package: `oracle.oci_db_observability_mcp_server`.
+- Discovery guidance permits reuse of applicable skill, tool, and schema
+  information from earlier calls instead of requiring the full workflow for
+  every invocation.

src/oci-db-observability-mcp-server/LICENSE.txt

@@ -0,0 +1,35 @@
+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.

src/oci-db-observability-mcp-server/README.md

@@ -0,0 +1,127 @@
+# OCI Database Observability MCP Server
+
+This package provides one MCP server for OCI Operations Insights (OPSI),
+Database Management (DBM), and OCI Monitoring observability workflows. It
+exposes three read-only compartment discovery tools plus four catalog discovery
+and invocation tools. The catalog contains read-only OCI SDK bindings and
+packaged metadata handlers.
+
+## Running
+
+### STDIO
+
+```sh
+uvx oracle.oci-db-observability-mcp-server
+```
+
+Use a named OCI CLI profile when required:
+
+```sh
+OCI_CONFIG_PROFILE=<profile_name> uvx oracle.oci-db-observability-mcp-server
+```
+
+### HTTP streaming
+
+```sh
+ORACLE_MCP_HOST=<bind_host> \
+ORACLE_MCP_PORT=<port> \
+ORACLE_MCP_BASE_URL=<public_base_url> \
+OCI_REGION=<region> \
+IDCS_DOMAIN=<idcs_domain> \
+IDCS_CLIENT_ID=<client_id> \
+IDCS_CLIENT_SECRET=<client_secret> \
+IDCS_AUDIENCE=<audience> \
+uvx oracle.oci-db-observability-mcp-server
+```
+
+Register `${ORACLE_MCP_BASE_URL}/auth/callback` in the OCI IAM confidential
+application. If `IDCS_REQUIRED_SCOPES` is unset, the default scope is
+`oci_mcp.db_observability.invoke` together with the standard OpenID scopes.
+The server uses `oracle-mcp-common` 0.1.2 or later for OCI authentication.
+
+## Discovery workflow
+
+1. For a compartment-scoped operation, use a user-provided compartment OCID.
+   For a name lookup, call `resolve_oci_compartment`; it searches the configured
+   discovery roots and returns matching OCIDs and paths. Configure one or more
+   comma-separated roots independently of OCI authentication:
+
+   ```sh
+   DBO_MCP_TENANCY_IDS=<tenancy_ocid>[,<another_tenancy_ocid>]
+   ```
+
+   Use the `id` from a unique match as `compartment_id` in subsequent operations.
+   If there are multiple matches, ask the user to select a returned path. If no
+   roots are configured, provide `root_compartment_ids` to the resolver or ask
+   the user for a root; do not invent an OCID. `list_oci_compartments` supports
+   direct browsing below an explicit root, or uses the configured root when
+   exactly one is configured. If the user provides an OCID, call
+   `get_oci_compartment` to validate it when needed.
+2. Call `list_dbo_skills` when the relevant capability is not already known.
+3. Call `list_dbo_tools` for selected skills when the required operation is not
+   already known.
+4. Call `describe_dbo_tool` when the selected tool's schema is unavailable,
+   outdated, or uncertain. Previously retrieved applicable results may be
+   reused.
+5. Call `invoke_dbo_tool` with arguments matching the known schema.
+
+The complete skill and tool catalogs are packaged as JSON under
+`oracle/oci_db_observability_mcp_server/metadata`. Skills organize
+read-only workflows such as inventory, diagnostics, performance, and fleet
+analysis. Their concise descriptions are MCP discovery metadata, not MCP
+resources; the detailed OEM.ai skill files are not packaged or required at
+runtime. The tool catalog contains OPSI, DBM, and OCI Monitoring operations;
+it does not expose the individual operations as MCP tools.
+
+## OCI Monitoring metric and alarm workflow
+
+The `database-and-infra-observability-metric-catalog` skill provides three
+local catalog tools (search, get, and list), one live metric reader, and three
+read-only alarm tools. First identify a metric using the local catalog, then
+read a specific metric with its exact namespace/name, explicit RFC 3339 time
+window, allowed dimensions, aggregation, interval, and resolution. The metric
+reader turns that request into MQL and makes one
+`MonitoringClient.summarize_metrics_data` call. Alarm definition and state
+tools each make one respective OCI Monitoring SDK call. No tool changes OCI
+resources.
+
+## Pagination
+
+Paginated operations accept an optional `page` argument. Responses contain the
+page data and a `nextPage` token when more results are available:
+
+```json
+{
+  "data": [],
+  "nextPage": "<token>"
+}
+```
+
+Pass the returned `nextPage` value as `page` in the next invocation. Stop when
+`nextPage` is null.
+
+## Development
+
+Run the unified server tests with:
+
+```sh
+make test project=oci-db-observability-mcp-server
+```
+
+Run repository lint with:
+
+```sh
+make lint
+```
+
+## 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.
+
+## License
+
+Copyright (c) 2026 Oracle and/or its affiliates.
+
+Released under the Universal Permissive License v1.0.

src/oci-db-observability-mcp-server/oracle/__init__.py

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

src/oci-db-observability-mcp-server/oracle/oci_db_observability_mcp_server/__init__.py

@@ -0,0 +1,10 @@
+"""
+Copyright (c) 2026, Oracle and/or its affiliates.
+Licensed under the Universal Permissive License v1.0 as shown at
+https://oss.oracle.com/licenses/upl.
+"""
+
+from importlib.metadata import version as distribution_version
+
+__project__ = "oracle.oci-db-observability-mcp-server"
+__version__ = distribution_version(__project__)