Skip to content

Group/Tag Filtering Implementation #840

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.

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

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from

Conversation

cliffhall
Copy link
Member

Groups and tags implementation. See SEP-1300 - Tool Filtering with Groups and Tags

Motivation and Context

It is an implementation for an SEP and not expected to be merged. It contains updates to the SDK, unit tests, integration tests, and examples

How Has This Been Tested?

In addition to unit tests and integration tests, there are client and server examples that work together:

Screenshot 2025-08-04 at 4 21 42 PM Screenshot 2025-08-04 at 4 22 31 PM

Breaking Changes

Nope.

Types of changes

  • 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 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

The implementation follows the MCP specification for filtering capabilities:

Server Capabilities: Servers can now declare support for filtering with the filtering capability, including whether list change notifications are supported.

Group Primitive: Groups are collections of tools that separate the server's toolspace by functionality or use case.

Tag Primitive: Tags are labels that can be attached to tools to denote cross-cutting concerns like status or operational safety.

Filter Parameter: The tools/list method now accepts a filter parameter that allows filtering tools by groups and tags.

Tool Definition: Tools can now be associated with groups and tags, which are included in the tool definition.

The implementation is fully backward compatible - if the filter parameter is omitted, all tools are returned as before.

In src/types.ts
* Added a new filtering capability to the ServerCapabilitiesSchema to allow servers to declare support for filtering groups and tags
* Created new schemas for groups and tags:
GroupSchema: Defines a group that contains tools, with name, title, and description
TagSchema: Defines a tag that can be attached to tools, with name and description
* Extended the ToolSchema to include optional groups and tags properties
* Added a ToolsFilterSchema to define filter parameters for the tools/list request
* Extended the ListToolsRequestSchema to include the filter parameter
* Added new request/response schemas for group and tag operations:
ListGroupsRequestSchema and ListGroupsResultSchema
ListTagsRequestSchema and ListTagsResultSchema
* Added notification schemas for group and tag list changes:
GroupListChangedNotificationSchema
TagListChangedNotificationSchema
Added type exports for all the new schemas

In src/client/index.ts

Added client-side methods to support the new filtering capabilities:

* Added imports for the new types and schemas
* Implemented listGroups() method to request a list of groups from the server
* Implemented listTags() method to request a list of tags from the server
* Updated the listTools() method to properly handle the filter parameter

In src/server/mcp.ts

Added server-side implementation for filtering capabilities:

* Added imports for the new types
* Added registration of the filtering capability in the McpServer constructor
* Added storage for registered groups and tags with _registeredGroups and _registeredTags properties
* Implemented request handlers for groups and tags:
  - setGroupRequestHandlers() for handling group-related requests
  - setTagRequestHandlers() for handling tag-related requests
* Updated the ListToolsRequestSchema handler to support filtering by groups and tags
* Extended the RegisteredTool type to include groups and tags
* Added methods to send group and tag list changed notifications:
  - sendGroupListChanged()
  - sendTagListChanged()
* Added methods to register groups and tags:
  - registerGroup(): Registers a group with name, title, and description
  - registerTag(): Registers a tag with name and description
In src/client/filtering.test.ts
* Tests client-side filtering capabilities
* Verifies listGroups and listTags methods work correctly
* Tests filtering tools by groups, tags, and combinations
* Verifies error handling when filtering capability is not available

In src/server/filtering.test.ts
* Tests server-side filtering capabilities
* Verifies group and tag registration, updating, and removal
* Tests filtering tools by groups, tags, and combinations
* Verifies that tools match ANY of the specified groups
* Verifies that tools match ALL of the specified tags

In src/integration-tests/filtering.test.ts
* End-to-end tests for filtering capabilities
* Tests listing groups and tags
* Tests filtering tools by groups, tags, and combinations
* Verifies correct behavior with real HTTP server and transports
The filtering examples demonstrate the implementation of the MCP filtering capabilities through a client-server application. These examples showcase how to organize tools into logical groups and tag them with cross-cutting concerns, allowing clients to filter tools to avoid LLM context overload.
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.

1 participant
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy