feat: add provider and action filtering to fetchTools()

[ryoppippi]

Summary

This PR introduces comprehensive filtering capabilities to the fetchTools() method in StackOneToolSet, enabling users to filter tools by providers and action patterns with glob support. These new filters can be combined with the existing account ID filtering for precise tool selection.

What Changed

Core Implementation

• Provider Filtering: Added providers option to filter tools by provider names (e.g., ['hibob', 'bamboohr'])

  • Case-insensitive matching for robustness
  • Extracts provider from tool name using provider_action convention

• Action Filtering: Added actions option to filter tools by action patterns

  • Supports exact action name matching (e.g., ['hris_list_employees'])
  • Supports glob patterns with wildcards (e.g., ['*_list_employees'])
  • Flexible pattern matching for dynamic tool selection

• Filter Combination: All filters (accountIds, providers, actions) can be combined for precise control

Code Changes

• Modified src/toolsets/stackone.ts:

  • Enhanced FetchToolsOptions interface with providers and actions fields
  • Implemented filterTools() private method for applying filters
  • Refactored fetchTools() to support new filtering logic

• Added comprehensive tests in src/toolsets/tests/stackone.mcp-fetch.spec.ts:

  • 11 new test cases covering all filtering scenarios
  • Tests for individual filters and all combinations
  • Edge case coverage

• Updated documentation in README.md:

  • New "Filtering Tools with fetchTools()" section
  • Code examples for all filtering patterns
  • Use case descriptions

• Enhanced examples/fetch-tools.ts:

  • Expanded to 7 distinct examples
  • Demonstrates each filtering option
  • Shows combined filter usage

Examples

Filter by Providers

const tools = await toolset.fetchTools({ 
  providers: ['hibob', 'bamboohr'] 
});

Filter by Actions (Exact Match)

const tools = await toolset.fetchTools({
  actions: ['hris_list_employees', 'hris_create_employee']
});

Filter by Actions (Glob Pattern)

// Get all "list employees" operations across providers
const tools = await toolset.fetchTools({ 
  actions: ['*_list_employees'] 
});

// Get all "list" operations
const tools = await toolset.fetchTools({ 
  actions: ['*_list_*'] 
});

Combine Multiple Filters

// Get specific operations from specific providers for specific accounts
const tools = await toolset.fetchTools({
  accountIds: ['account-123'],
  providers: ['hibob'],
  actions: ['*_list_*']
});

Why These Changes

These filtering capabilities are essential for:

1. Precision Tool Selection: When working with LLM agents, reducing the number of available tools improves accuracy and reduces token usage
2. Multi-Provider Environments: Users often want to limit operations to specific HR/CRM/ATS providers
3. Operation-Specific Workflows: Some workflows only need specific types of operations (e.g., read-only operations)
4. Performance Optimization: Filtering reduces the tool catalog size, improving performance
5. Multi-Account Support: Combined with account filtering, enables granular control in multi-tenant scenarios

Testing

• All 145 tests pass successfully
• Lint checks pass
• No breaking changes to existing API
• Backward compatible with all existing code

Use Cases

1. Read-only workflows: actions: ['*_list_*', '*_get_*']
2. Provider-specific operations: providers: ['hibob']
3. Employee management focus: actions: ['*_employees*']
4. Multi-account + specific provider: accountIds: ['acc-123'], providers: ['bamboohr']

Related Issues

This feature completes the dynamic tool fetching capabilities introduced in ENG-11034.

---

Summary by cubic

Adds provider and action filters (with glob patterns) to fetchTools() so you can narrow the tool catalog by provider and operation alongside existing account ID filtering. This delivers the dynamic MCP tool fetching requested in ENG-11034.

• New Features
  • providers option: case-insensitive; provider inferred from tool name prefix (provider_action).
  • actions option: supports exact names and glob patterns like "list".
  • Filters can be combined with accountIds for precise selection.
  • Refactored fetchTools() with a new private filterTools(); backward compatible. Updated README and examples; added tests for all filter combinations.

[Copilot]

Pull Request Overview

This PR adds provider and action filtering capabilities to the fetchTools() method, enabling users to filter tools by provider names and action patterns (with glob support) in addition to the existing account ID filtering. These filters can be combined for precise tool selection in multi-provider, multi-account scenarios.

Key Changes:

• Added providers and actions optional parameters to FetchToolsOptions interface
• Implemented filterTools() private method with case-insensitive provider matching and glob pattern support for actions
• Enhanced documentation with filtering examples and use cases

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
src/toolsets/stackone.ts	Core implementation of provider and action filtering logic with filterTools() method
src/toolsets/tests/stackone.mcp-fetch.spec.ts	Comprehensive test suite covering individual filters and combinations
examples/fetch-tools.ts	Expanded examples demonstrating all filtering options
README.md	Documentation updates with filtering examples and use cases

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/StackOneHQ/stackone-ai-node/@stackone/ai@124

commit: 7df3af9

[willleeney]

LGTM

[cubic-dev-ai]

1 issue found across 4 files

Prompt for AI agents (all 1 issues)

Understand the root cause of the following 1 issues and fix them.


<file name="examples/fetch-tools.ts">

<violation number="1" location="examples/fetch-tools.ts:47">
This provider-only example still inherits the account filter set earlier, so it will not actually demonstrate provider filtering in isolation and may produce empty results when those accounts lack these providers. Please clear the account IDs before this call or pass accountIds explicitly.</violation>
</file>

_{React with 👍 or 👎 to teach cubic. Mention @cubic-dev-ai to give feedback, ask questions, or re-run the review.}

[cubic-dev-ai]

This provider-only example still inherits the account filter set earlier, so it will not actually demonstrate provider filtering in isolation and may produce empty results when those accounts lack these providers. Please clear the account IDs before this call or pass accountIds explicitly.

Prompt for AI agents

Address the following comment on examples/fetch-tools.ts at line 47:

<comment>This provider-only example still inherits the account filter set earlier, so it will not actually demonstrate provider filtering in isolation and may produce empty results when those accounts lack these providers. Please clear the account IDs before this call or pass accountIds explicitly.</comment>

<file context>
@@ -24,10 +24,59 @@ const toolset = new StackOneToolSet({
+
+// Example 4: Filter by providers
+console.log(&#39;\n=== Example 4: Filter by providers ===&#39;);
+const toolsByProviders = await toolset.fetchTools({
+  providers: [&#39;hibob&#39;, &#39;bamboohr&#39;],
+});
</file context>