8000 Add `pathVariableNames` and `queryVariableNames` getters in `UriTemplate` by Mubashwer · Pull Request #609 · modelcontextprotocol/typescript-sdk · GitHub
[go: up one dir, main page]
Skip to content

Add pathVariableNames and queryVariableNames getters in UriTemplate #609

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add pathVariableNames and queryVariableNames getters in UriTemplate #609

wants to merge 1 commit into from
+83 −0

Conversation

Mubashwer
Copy link
B572
@Mubashwer Mubashwer commented Jun 10, 2025 •
edited
Loading

This PR adds two new getter methods to the UriTemplate class that distinguish between path-like variables (which identify core resources) and query-like variables (which are optional parameters). This will enable the MCP Inspector to allow resource browsing with only essential path variables filled, while treating query parameters as optional filters.

Motivation and Context

The MCP Inspector currently requires all URI template variables to be filled before allowing reading of resources from resource templates, which makes it difficult to explore available resources and understand what variables are needed. Some query parameters MAY be optional. This change enables better resource discovery by distinguishing between path-like variables (which identify the core resource) and query-like variables (which are optional filters/parameters).

This addresses the need for more intuitive resource browsing in MCP Inspector, where users should be able to access resources with only essential path variables while treating query parameters as optional enhancements.

How Has This Been Tested?

  • Added comprehensive test suite covering all RFC 6570 expansion operators
  • Tests for edge cases (templates with no variables, only path variables, only query variables)
  • Validated correct classification of mixed templates with both path and query variables
  • All existing tests continue to pass, ensuring backward compatibility
  • Tested with real MCP resource templates like database://users/{id}{?limit,offset}

Breaking Changes

No breaking changes. This is a purely additive feature that maintains full backward compatibility with existing code.

Types of changes

  • New feature (non-breaking change which adds functionality)
  • Bug fix (non-breaking change which fixes an issue)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have added or updated documentation as needed

Additional context

Implementation Details:

  • pathVariableNames: Returns variables from path-like expansions ("", "+", "#", ".", "/" operators)
  • queryVariableNames: Returns variables from query-like expansions ("?", "&" operators)
  • Classification based on RFC 6570 expansion operators, not semantic assumptions
  • Maintains existing variableNames getter for full compatibility

Use Case Example:

const template = new UriTemplate("database://users/{id}/posts{?limit,offset}");
template.pathVariableNames;  // ["id"] - structurally required
template.queryVariableNames; // ["limit", "offset"] - optional parameters

This change will enable MCP Inspector to allow browsing database://users/123/posts without requiring query parameters, while still showing what optional filters are available.

RFC 6570 Compliance:

  • Path-like variables affect URI structure when omitted
  • Query-like variables only affect query parameters when omitted
  • Both types are technically optional per RFC 6570, but have different structural implications
  • Implementation follows RFC 6570 expansion mechanics precisely

@Mubashwer
Add pathVariableNames and queryVariableNames getters in UriTemplate
e05d66e 
Add new getter methods to UriTemplate class to distinguish between path-like
and query-like variables based on RFC 6570 expansion operators. This enables
better resource browsing in MCP Inspector by identifying which variables are
structurally required vs. optional.

**New Features:**
- `pathVariableNames`: Returns variables used in path-like expansions
  - Simple expansion: `{var}`
  - Reserved expansion: `{+var}`
  - Fragment expansion: `{#var}`
  - Label expansion: `{.var}`
  - Path segment expansion: `{/var}`

- `queryVariableNames`: Returns variables used in query-like expansions
  - Form-style query: `{?var}`
  - Query continuation: `{&var}`

**Use Case:**
This change will improve MCP Inspector UX by allowing users to browse resource templates
with only path variables filled, while treating query variables as optional
filters. For example, with template `database://users/{id}{?limit,offset}`:
- Path variables (`id`) identify the core resource
- Query variables (`limit`, `offset`) are optional filtering parameters

**Technical Details:**
- Classification based on RFC 6570 expansion operators, not semantic assumptions
- Path-like variables affect URI structure when omitted
- Query-like variables only affect query parameters when omitted
- Maintains backward compatibility with existing `variableNames` getter

**Tests:**
- Added comprehensive test suite covering all operator types
- Tests for edge cases (no variables, only path, only query)
- Validates correct classification of mixed templates
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
1 participant
@Mubashwer
0