Recovery mcp server

[gsharini]

Introduce a new MCP server: OCI Autonomous Recovery Service MCP Server (oci-recovery-mcp-server). This server exposes tools to query and summarize Oracle Cloud Infrastructure (OCI) Autonomous Recovery Service resources such as Protected Databases, Protection Policies, Recovery Service Subnets, DB Homes/Databases, DB Systems, and related metrics. It also includes a comprehensive test suite for the new tools and models, along with linting fixes.

Key changes:

• New package at src/oci-recovery-mcp-server with:

  • pyproject.toml and package scaffolding
  • Server implementation (oracle/oci_recovery_mcp_server/server.py)
  • Data models (oracle/oci_recovery_mcp_server/models.py)
  • init files and README/License

• New unit tests:

  • oracle/oci_recovery_mcp_server/tests/test_recovery_tools.py
  • oracle/oci_recovery_mcp_server/tests/test_recovery_database_tools.py

• Lint fixes and minor improvements, plus a few additional custom tools

Implemented tools (server API surface):

• Identity/compartment helper:

  • get_compartment_by_name_tool

• Recovery Service - Protected Databases and health:

  • list_protected_databases
  • get_protected_database
  • summarize_protected_database_health
  • summarize_protected_database_redo_status
  • summarize_backup_space_used

• Recovery policies and subnets:

  • list_protection_policies
  • get_protection_policy
  • list_recovery_service_subnets
  • get_recovery_service_subnet

• Recovery metrics:

  • get_recovery_service_metrics (SpaceUsedForRecoveryWindow, ProtectedDatabaseSize, ProtectedDatabaseHealth, DataLossExposure)

• Database/backup surface for context:

  • list_databases, get_database
  • list_backups, get_backup
  • summarise_protected_database_backup_destination
  • get_db_home
  • list_db_systems, get_db_system

Motivation:

• Provide an MCP-compliant interface for OCI Recovery Service operations, enabling tools-based automation and summarization within MCP-enabled editors/agents.
• Add test coverage to ensure correctness of request shaping, response handling, and summary logic.

Dependencies:

• Uses OCI Python SDK (already standard in this repository’s ecosystem).
• No new external runtime dependencies beyond those specified in the new subpackage’s pyproject.toml.

Fixes # N/A (feature addition)

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update (new server README added; main docs may need a link/section)

How Has This Been Tested?

• Added unit tests for tool behavior and models:

  • oracle/oci_recovery_mcp_server/tests/test_recovery_tools.py
  • oracle/oci_recovery_mcp_server/tests/test_recovery_database_tools.py

• Tests validate request building, mock-backed responses, health/redo/backup summaries, and error handling paths.

Reproduce locally:

• Option A (pip):

  • python -m venv .venv && source .venv/bin/activate
  • pip install -U pip
  • pip install -e src/oci-recovery-mcp-server[dev]
  • pytest -q src/oci-recovery-mcp-server/oracle/oci_recovery_mcp_server/tests

• Option B (uv):

  • cd src/oci-recovery-mcp-server
  • uv pip install -e ".[dev]"
  • uv run pytest -q

Notes:

• Tests mock OCI client interactions and do not require live OCI credentials.

• Test A: Tool and model unit tests (mocked)

• Test B: Summary computations (health, redo, backup space)

Test Configuration:

• Firmware version: N/A
• Hardware: N/A
• Toolchain: Python 3.x, pytest
• SDK: OCI Python SDK (mocked in tests)

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (new server README)
• My changes generate no new warnings
• I have added tests that prove my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules

[cboffa13]

This tool should exist within the identity MCP server

[gsharini]

Thanks for the review comment — I agree that, compartment lookup is an identity concern and the tool already exists in the identity MCP server.

But, our intent here is to keep the Recovery Service MCP server self-sufficient from a user’s perspective. If this tool is removed, users would be required to configure multiple MCP servers (identity + recovery) just to perform basic recovery workflows, which increases setup friction and adoption complexity.

Please let me know your view on this.

[cboffa13]

Suggested change

	- summarise_protected_database_backup_destination
	- summarize_protected_database_backup_destination

[gsharini]

@cboffa13 Can you review the changes merged in response to the comments?

[gsharini]

Can someone please review and help merge this code ?

[gsharini]

Sample Prompt and Response:

get me summary of redo status and health status of all protected db in devteam compartment

MCP output:
Redo status summary tool response:
{"compartmentId":"ocid1.compartment.oc1..aaaaaa...","region":"us-phoenix-1","enabled":1,"disabled":2,"total":3}

Health summary tool response:
{"compartmentId":"ocid1.compartment.oc1..aaaaaa...","region":"us-phoenix-1","protected":2,"warning":0,"alert":1,"unknown":0,"total":3}

Other Prompts:

1. get me list of backups of this db : ocid1.database.oc1.phx.anyhqljrhlxr34qaqhgeoqdec...vjigfh7xbbp4eaxwiq
2. get me list of protection policy in the compartment devteam

[gsharini]

OCI dash board prompt and its response:

`You are an expert dashboard generator. You very well know how to generate a presentable charts for the executives .
Make sure the chart is loadable and there are no errors while loading chart.

Visualise OCI Recovery - Dashboard charts in one html document with below metrics in devteam compartment.
Display the Title - OCI Recovery - Dashboard
Under the Title, mention the compartment name.
Under this compartment name add a note : Generated using Recovery Service MCP Server
Add the date of report generation

Main page ( Overview)
In first row, summarise base db systems based on backup destination - DBRS, OBJECT_STORE or UNCONFIGURED using donut chart - using tool summarise_protected_database_backup_destination . Use title - Databases categorised by backup destination. Replace DBRS with "RecoveryService” while generating the report.
In another frame, first row, second column, With title Protected Database Space : report total backup space used by protected databases - using tool summarize_backup_space_used. Note : Space used by ACTIVE/DELETE SCHEDULED protected databases
In Second Row first column, Summarise protected database based on lifecycle status using donut chart - Title - protected databases by lifecycle state. Make sure the values are based on actual data. Double check this
In Second row, summarise protected databases on health status - PROTECTED, WARNING, ALERT using donut chart - using tool summarize_protected_database_health - Title - ACTIVE protected databases by health state
In Second row, summarise protected databases on realtime redo status - ENABLED, DISABLED using donut chart - using tool summarize_protected_database_redo_status -- Title - ACTIVE protected databases by real time redo
In the Fourth row, Report the protected databases with OCID, database db unique name, health status, lifecycle state, redo status, backup space used  in tabular format . Filterable columns - Health status, Redo status , life cycle state . This data is very important. extract details very carefully from list protecetd datbase output and carefully map the columns to the OCIDs. Be very diligent while filling up this table. Dont miss the filters.

In another tab named - Backup Details
Tool to use list backups with compartment id as argument
You are an expert dashboard generator. You very well know how to generate a presentable charts for the executives .
Make sure the chart is loadable and there are no errors while loading chart. The lines in graph are clearly visible and well positioned.

Generate a line chart showing backup creation timelines for databases in the mentioned compartment. Each database is represented by a distinct line, with points marking individual backup events based on 'time_started'. The chart is styled for executive presentation, with a clean layout, legend, and tooltips.
X axis - Creation date/ Start date
Y axis - db_unique_name
Generate a line chart showing time taken by each backup for databases in the mentioned compartment. Each database is represented by a distinct line, with points marking individual backup events based on ‘duration'. If user hovers over individual points then they should gets details such as exact duration and type of backup (FULL or INCREMENTAL)  

• X axis: Creation date / Start date
• Y axis: duration_minutes.
  Give your insight on
  If any backup has taken more time or less time than usual pattern
  Is there any backup missing in the pattern
  If backup is Manually taken or LTR call that out separately

IMPORTANT: 
Make sure charts are loadable and renderable clearly in html. Double check this condition.
There should be no missing line charts
Donot add date/time on the points unless user hovers over that point.

In another tab named - Backup space usage
Tool to use get_recovery_service_metrics and resolution used 1 day.
Generate a line chart of backup space used by each protected databases in last 5 days - using tool get_recovery_service_metrics and metricName SpaceUsedForRecoveryWindow . Each protected database is represented by a distinct line with points marking individual space.
Give your insight on
If there are any anomolies in the space usage pattern.
Any other space anomoly you can think of

Add an executive KPI summary row directly below the dashboard title.

Create 4 KPI cards displayed horizontally using Bootstrap grid:

1. Total Protected Databases
2. Healthy Databases (%)
3. Redo Shipping Enabled (%)
4. Total Backup Space Used (GB)

Rules:

• Use existing dashboard data to calculate KPI values.
• KPI cards must be visually compact and equal height.
• Each KPI card should contain:
  • Small uppercase label
  • Large bold metric value
  • Optional subtext (e.g. "of 3 databases")

Styling:

• Use soft card backgrounds with rounded corners.
• Center-align KPI content.
• Use large font (2–2.5rem) for KPI numbers.
• Use subtle shadows.
• Maintain spacing with Bootstrap g-4.

Layout:

• KPI row must appear ABOVE all charts.
• Dashboard width remains 75vw.
• On mobile, stack KPI cards vertically.

Data logic:

• Total Protected Databases = count of protected databases.
• Healthy % = (PROTECTED / total) * 100.
• Redo Enabled % = (ENABLED / total) * 100.
• Total Backup Space = sum of space used.

After KPIs, keep charts as secondary visual detail.

IMPORTANT

Layout rules for HTML dashboard:

• Wrap all content in a .dashboard-container:
  width: 75vw;
  max-width: 1200px;
  margin: 0 auto;
• Center the dashboard horizontally.
• Do NOT use full screen width.
• On mobile (<768px), expand dashboard to 95vw.

Chart container sizing:

• Do NOT use a single default height for all charts.
• Overview donut charts MUST be compact:
  height: 260px.
• Timeline / line charts:
  height: 360px.
• Space usage charts:
  height: 300px.
• Apply CSS classes per chart type (overview-donut, timeline-chart, space-chart).
• Ensure donuts appear compact and not vertically stretched.

When using Chart.js:

• NEVER use custom HTML legends.
• NEVER use absolute positioning over canvas.
• Always use native Chart.js legend positioned on the right.
• Add layout.padding = 20 to every chart.
• For doughnut charts:
  cutout: '65%'
  radius: '85%'
• Ensure charts fit inside containers without clipping.
• Avoid overlapping elements.
• Maintain clean spacing between panels.
• Optimize layout for presentation-quality visuals.
  Make sure chart sizes are equal and fit well inside demarcation.
  Make sure there are no rendering issues
  Dont generate trucated html file.
  Make sure its a complete file wihtout any syntax issues
  Make sure legends are written on the rightside of donut chart and with in frame
  Show all the legends and next to legends mention the count as well in brackets
  Make sure titles are on the top of the donut chart .
  Makesure title, donut chart and legends fit with in the frame

Always render charts for every tab
Include required JS adapters
Initialize charts after tab activation

Use soft colors in the chart - executive appealing colors
Demarcate between the rows Since this is a dashboard make sure user gets the visbility of most charts without scrolling.
Create a responsive layout minimizing scrolling `

Response is attached as HTML:

oci_recovery_dashboard_14.html

[gebhardtr]

unclear why this is in scope for the MCP server; is this a leftover prompt for an external integration/test?

[gsharini]

Hi Richard,
Thanks for looking into this PR.
The oci_recovery_service_dashboard.txt is an example prompt that we are planning to share with users to give better idea on how extensively this MCP Server can be used. We plan to add a few more, covering additional APIs and usecases. For anyone having access to our MCP server code, if they need a readymade prompt to use, they could use it.
Also there is a plan to blog this point when our PMs start promoting it .

[gebhardtr]

ok, but it will be downloaded by everyone that uses your server (whether they view/use it or not). Would it be better to include 1-2 examples with a link to the post in the README?

[gsharini]

Thanks for the idea. We can do a link to post in the README , which then can take users to a site/post which talks about recovery service and its mcp server in a great deal.
But in order to do that we need this MCP server merged, then publish the blog on this and then create PR to add the blog/post link here.
I will create a follow up PR immediately with the placeholder-link in README and remove the prompt txt in it.
As this whole publishing process can take 1-2 weeks. , meanwhile, can this file go in this PR ?

What do you suggest ?

1. We can do link to post and come back update the README, let this file go in the repo for the interim
2. Remove the file now in this PR and do it once post/link is available.

Please let me know, I am fine with either approach.