Skip to content

Conversation

@oliveregger
Copy link
Member

@oliveregger oliveregger commented Oct 20, 2025

Summary by Sourcery

Enhance MCP Server integration by adding support for listing and passing extra validation parameters, updating request handling and serialization utilities, logging validation completion, and refreshing documentation and versioning to 4.0.14.

New Features:

  • Add a new MCP tool 'list-validation-parameters' to enumerate extra validation parameters
  • Implement retrieval of additional validation parameters in the MCP bridge

Enhancements:

  • Allow passing custom validation parameters or default AI flag in validation calls
  • Extend RequestBuilder to include dynamic query/search parameters in requests
  • Add serializeR5 helper in CrossVersionResourceUtils for FHIR R5 elements
  • Log completion of validation runs in MatchboxEngine

Build:

  • Bump project version to 4.0.14 across all modules
  • Publish a new Release 4.0.14 entry in the changelog

Documentation:

  • Update MCP endpoint URLs and add an example config for remote MCP clients with validation parameters
  • Register the 'validation-with-ai' tutorial in mkdocs navigation

@sourcery-ai
Copy link

sourcery-ai bot commented Oct 20, 2025

Reviewer's Guide

This PR further integrates the MCP Server by adding a new tool to list validation parameters, extending the validation call pipeline to accept custom parameters, enhancing request building and resource serialization, updating documentation and endpoints, bumping project versions, and adding completion logging.

Sequence diagram for validation with custom parameters in MCP integration

sequenceDiagram
    participant Client
    participant MCPMatchboxBridge
    participant RequestBuilder
    participant RestfulServer
    participant MockHttpServletResponse

    Client->>MCPMatchboxBridge: Call getValidationResult with contextMap
    MCPMatchboxBridge->>MCPMatchboxBridge: Parse validationparams from contextMap
    MCPMatchboxBridge->>RequestBuilder: Build request with custom query params
    RequestBuilder->>RestfulServer: handleRequest()
    RestfulServer->>MockHttpServletResponse: Write response
    MCPMatchboxBridge->>Client: Return validation result
Loading

Class diagram for new and updated MCP integration classes

classDiagram
    class McpMatchboxBridge {
        +generateTools()
        +getExtraValidationParameters(contextMap, interaction)
        +getValidationResult(contextMap, interaction)
    }
    class ToolFactory {
        +listValidationParameters()
        +listFhirProfilesToValidateFor()
    }
    class RequestBuilder {
        +buildRequest()
    }
    class CrossVersionResourceUtils {
        +serializeR5(Resource, MatchboxFhirFormat, Writer)
        +serializeR5(IBase, MatchboxFhirFormat, Writer)
    }
    McpMatchboxBridge --> ToolFactory : uses
    McpMatchboxBridge --> RequestBuilder : uses
    McpMatchboxBridge --> CrossVersionResourceUtils : uses
Loading

File-Level Changes

Change Details Files
Introduce a new MCP tool for listing extra validation parameters and its call handler
  • Register a new SyncToolSpecification for list-validation-parameters in generateTools
  • Implement getExtraValidationParameters to fetch, parse, filter, and serialize OperationDefinition parameters
  • Add listValidationParameters method and JSON schema in ToolFactory
matchbox-server/src/main/java/ca/uhn/fhir/rest/server/McpMatchboxBridge.java
matchbox-server/src/main/java/ch/ahdis/matchbox/mcp/ToolFactory.java
Support custom validation parameters in the validation call
  • Parse “validationparams” argument into a query map when present
  • Default to analyzeOutcomeWithAI=false if no custom parameters provided
matchbox-server/src/main/java/ca/uhn/fhir/rest/server/McpMatchboxBridge.java
Enhance RequestBuilder to forward dynamic query/search parameters
  • Detect ‘query’ or ‘searchParams’ maps in config
  • Add each key–value pair as HTTP request parameters
matchbox-server/src/main/java/ca/uhn/fhir/jpa/starter/mcp/RequestBuilder.java
Add an R5 serialization helper for FHIR elements
  • Introduce serializeR5 overload in CrossVersionResourceUtils for IBase elements
matchbox-server/src/main/java/ch/ahdis/matchbox/util/CrossVersionResourceUtils.java
Update tutorials, navigation, and changelog for the new MCP endpoint
  • Change MCP endpoint URLs to /matchboxv3/mcp/message in validation-with-ai-tutorial
  • Insert JSON configuration snippet for MCP client
  • Add tutorial to mkdocs nav
  • Bump changelog entry for 4.0.14 release
docs/validation-with-ai-tutorial.md
docs/changelog.md
mkdocs.yml
Bump project version to 4.0.14 across modules
  • Update parent.version in matchbox-engine/pom.xml, matchbox-server/pom.xml, and root pom.xml
matchbox-engine/pom.xml
matchbox-server/pom.xml
pom.xml
Add completion logging in the MatchboxEngine validator
  • Log validation completion details (URL, version, date) in validate method
matchbox-engine/src/main/java/ch/ahdis/matchbox/engine/MatchboxEngine.java

Possibly linked issues


Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

Copy link

@sourcery-ai sourcery-ai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey there - I've reviewed your changes - here's some feedback:

  • Consider refactoring the duplicated FHIR request/response handling in getExtraValidationParameters and existing call handlers into a shared helper to reduce boilerplate.
  • The manual JSON array construction in getExtraValidationParameters appends a trailing comma before the closing bracket, leading to invalid JSON—either trim the last comma or use a JSON builder.
  • Parsing validationparams as a comma-separated string is brittle—consider accepting and validating a structured JSON object for more reliable parameter handling.
Prompt for AI Agents
Please address the comments from this code review:

## Overall Comments
- Consider refactoring the duplicated FHIR request/response handling in getExtraValidationParameters and existing call handlers into a shared helper to reduce boilerplate.
- The manual JSON array construction in getExtraValidationParameters appends a trailing comma before the closing bracket, leading to invalid JSON—either trim the last comma or use a JSON builder.
- Parsing validationparams as a comma-separated string is brittle—consider accepting and validating a structured JSON object for more reliable parameter handling.

## Individual Comments

### Comment 1
<location> `docs/validation-with-ai-tutorial.md:90` </location>
<code_context>
 ```

-The MCP-Server can be reached at the endpoint `http://<<your-url>>/matchbox/mcp/sse`
+The MCP-Server can be reached at the endpoint `http://<<your-url>>/matchbox(v3)/mcp/message`

 ### Setting up matchbox for Claude Desktop
</code_context>

<issue_to_address>
**suggestion:** Inconsistent use of parentheses in endpoint URL.

Ensure the endpoint format is consistent across all documentation references.

Suggested implementation:

```
The MCP-Server can be reached at the endpoint `http://<<your-url>>/matchbox/v3/mcp/message`

```

Review the rest of the documentation for any other references to the endpoint and update them to use `/matchbox/v3/mcp/message` (without parentheses) for consistency.
</issue_to_address>

Sourcery is free for open source - if you like our reviews please consider sharing them ✨
Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.

```
The MCP-Server can be reached at the endpoint `http://<<your-url>>/matchbox/mcp/sse`
The MCP-Server can be reached at the endpoint `http://<<your-url>>/matchbox(v3)/mcp/message`
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: Inconsistent use of parentheses in endpoint URL.

Ensure the endpoint format is consistent across all documentation references.

Suggested implementation:

The MCP-Server can be reached at the endpoint `http://<<your-url>>/matchbox/v3/mcp/message`

Review the rest of the documentation for any other references to the endpoint and update them to use /matchbox/v3/mcp/message (without parentheses) for consistency.

@oliveregger oliveregger merged commit 2bbaab8 into main Oct 22, 2025
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants