feat: Add unraid_api tool for schema introspection and raw queries

[nkissick-del]

Overview

Adds a new advanced capability for the MCP server: Direct API Introspection.

Context

See the schema directly to construct custom queries when pre-built tools are insufficient.

New Tools

• introspect_schema: Allows lookup of specific GraphQL types or root fields.
• query_unraid_api: Executes raw GraphQL queries.
  • SAFEGUARD: Explicitly blocks any query containing mutation operations to strictly enforce read-only access.

Verification

• Tested schema introspection to verify it returns correct type definitions.
• Verified that write operations are correctly blocked by the safety filter.

---

Summary by cubic

Adds API tools to explore the Unraid GraphQL schema and run read-only queries. Enables advanced querying while blocking write operations.

• New Features
  • Added introspect_schema to fetch root fields or details for a specific type.
  • Added query_unraid_api to run raw GraphQL queries with mutation blocking and variable validation.
  • Registered the tools via register_api_tools in server startup.

^{Written for commit 4713e1e. Summary will update on new commits.}

[coderabbitai]

Warning

Rate limit exceeded

@nkissick-del has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 24 minutes and 5 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cubic-dev-ai]

1 issue found across 2 files

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="unraid_mcp/tools/api.py">

<violation number="1" location="unraid_mcp/tools/api.py:205">
P2: Regex-based mutation detection blocks valid read-only queries when the word “mutation” appears as an identifier (operation name, field, alias, argument), causing false positives and making the safety check fragile.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: Regex-based mutation detection blocks valid read-only queries when the word “mutation” appears as an identifier (operation name, field, alias, argument), causing false positives and making the safety check fragile.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At unraid_mcp/tools/api.py, line 205:

<comment>Regex-based mutation detection blocks valid read-only queries when the word “mutation” appears as an identifier (operation name, field, alias, argument), causing false positives and making the safety check fragile.</comment>

<file context>
@@ -0,0 +1,225 @@
+
+        # Block mutations
+        stripped = _strip_comments(graphql_query)
+        if re.search(r"\bmutation\b", stripped, re.IGNORECASE):
+            raise ToolError(
+                "Mutations are not allowed through this tool. "
</file context>