feat!: remove deprecated OAS-based getTools, migrate to fetchTools only #148

ryoppippi · 2025-12-05T14:46:25Z

Summary

Remove all deprecated OpenAPI Specification (OAS) based tool generation and migrate exclusively to the MCP-based fetchTools() API.

Breaking Changes

getTools(), getTool(), loadTools(), and getStackOneTools() methods removed
OpenAPIToolSet class removed
OpenAPI spec imports from src/openapi/ removed
OpenAPIToolSetConfig type removed

Changes

Deleted:

src/openapi/ directory (parser, loader, generated specs, tests)
scripts/fetch-specs.ts and tests
.github/workflows/check-oas-updates.yml
src/toolsets/openapi.ts
Deprecated examples using getTools()

Modified:

StackOneToolSet - now only exposes fetchTools()
Base ToolSet - removed this.tools, getTools(), getTool()
Updated all examples to use fetchTools()
Updated all tests for new API
Updated README documentation

Migration

Before:

const toolset = new StackOneToolSet();
const tools = toolset.getTools({ verticals: ['hris'] });

After:

const toolset = new StackOneToolSet();
const tools = await toolset.fetchTools({ actions: ['hris_*'] });

Test plan

All 141 unit tests pass
Example tests pass
Build succeeds
No publint issues

Summary by cubic

Removed all OpenAPI (OAS) tooling and moved the SDK to a single MCP-based fetchTools() API. This breaking change simplifies the API, removes OAS maintenance, and updates docs, examples, tests, and CI.

Refactors
- StackOneToolSet now only exposes fetchTools(); removed getTools(), getTool(), loadTools(), getStackOneTools().
- Deleted OpenAPIToolSet, OpenAPI parser/loader, generated specs, and related exports/tests/examples.
- Removed OAS fetch scripts and GitHub workflow; cleaned package scripts and tsdown config.
- Updated README and remaining examples to use fetchTools(); adjusted tests (feedback tool included); removed unused constants.
Migration
- Replace getTools(...) with await fetchTools({ actions: [...] }).
- Stop importing OpenAPIToolSet and any src/openapi code; use StackOneToolSet only.
- Remove usage of fetch:specs and test:scripts; prepack now runs build.

^{Written for commit 84d7750. Summary will update automatically on new commits.}

Remove the entire src/openapi/ directory containing: - Generated OpenAPI spec TypeScript files for all verticals (ATS, CRM, Documents, HRIS, IAM, LMS, Marketing, Messaging, Screening, Ticketing) - OpenAPI parser that converted OAS to tool definitions - OpenAPI loader for loading specs from files - Associated tests and snapshots This code is no longer needed as the SDK now exclusively uses fetchTools() to retrieve tool definitions via MCP. BREAKING CHANGE: OpenAPI spec imports from src/openapi/ are removed

Remove scripts/fetch-specs.ts and its test file that were used to download OpenAPI specifications from StackOne's API and generate TypeScript files. These scripts are no longer needed as tool definitions are now fetched dynamically via MCP using fetchTools().

Remove the GitHub Actions workflow that checked for OpenAPI spec updates. This workflow is no longer needed as the SDK no longer bundles pre-generated OpenAPI specifications.

Remove the OpenAPIToolSet class that provided toolset functionality based on OpenAPI specifications: - src/toolsets/openapi.ts - the main OpenAPIToolSet class - src/toolsets/tests/openapi.spec.ts - associated tests - src/toolsets/tests/fixtures/petstore.json - test fixture - src/toolsets/tests/__snapshots__/stackone.spec.ts.snap - snapshots BREAKING CHANGE: OpenAPIToolSet is no longer exported. Use StackOneToolSet.fetchTools() instead.

Remove deprecated methods from StackOneToolSet and base ToolSet: StackOneToolSet: - Remove loadTools() that loaded tools from bundled OAS specs - Remove getStackOneTools() alias - Remove getTools()/getTool() inherited methods - Keep only fetchTools() for MCP-based tool retrieval ToolSet (base): - Remove this.tools property for storing loaded tools - Remove getTools() and getTool() methods - Keep _matchesFilter() and _matchGlob() for filtering BREAKING CHANGE: getTools(), getTool(), loadTools(), and getStackOneTools() methods are removed. Use fetchTools() instead.

Update public exports to remove OpenAPI-related items: src/index.ts: - Remove OpenAPIToolSet export - Remove OpenAPIToolSetConfig type export - Keep StackOneToolSet and related exports src/toolsets/index.ts: - Remove OpenAPIToolSet re-export - Remove OpenAPIToolSetConfig type re-export BREAKING CHANGE: OpenAPIToolSet and OpenAPIToolSetConfig are no longer exported from the package.

Remove the SPECS constant array that listed all supported OpenAPI specification verticals (ats, crm, documents, hris, iam, lms, marketing, messaging, screening, stackone, ticketing). This constant was used by the spec fetching scripts and is no longer needed with the MCP-based approach.

Remove npm scripts that were used for OpenAPI spec management: - fetch:specs - fetched latest OAS from StackOne API - rebuild - ran fetch:specs followed by build - test:scripts - ran tests for the fetch scripts These scripts are no longer needed as tool definitions are now retrieved dynamically via MCP.

Remove the onSuccess hook that cleaned up sourcemap files for the generated OpenAPI spec files. This cleanup step is no longer needed as the OAS generated files have been removed from the codebase.

Remove example files that demonstrated the deprecated OAS-based getTools() API: - openapi-toolset.ts - OpenAPIToolSet usage example - account-id-usage.ts - account ID configuration example - custom-base-url.ts - custom base URL example - error-handling.ts - error handling patterns - experimental-document-handling.ts - document handling example - filters.ts - tool filtering example These examples used the deprecated getTools()/getStackOneTools() methods. See the updated examples for fetchTools() usage.

Update remaining examples to use the MCP-based fetchTools() API: - ai-sdk-integration.ts - AI SDK integration example - human-in-the-loop.ts - human validation workflow example - meta-tools.ts - meta tools for dynamic discovery - openai-integration.ts - OpenAI integration example - index.ts - example index file Changes include: - Replace getTools() with fetchTools() - Update imports to remove OpenAPI dependencies - Use async/await for tool fetching - Update comments to reflect MCP-based approach

Update test files to reflect the removal of OAS-based methods: src/tests/exports.spec.ts: - Remove assertions for OpenAPIToolSet export - Keep assertions for StackOneToolSet and other exports src/toolsets/tests/base.spec.ts: - Remove tests for getTools() and getTool() methods - Keep tests for filtering functionality src/toolsets/tests/stackone.spec.ts: - Remove tests for loadTools(), getTools(), getStackOneTools() - Keep tests for fetchTools() functionality src/toolsets/tests/stackone.mcp-fetch.spec.ts: - Update expected tool counts to include feedback tool (+1) - Add assertions for meta_collect_tool_feedback presence

Rewrite README.md to document the MCP-based fetchTools() API: - Remove all references to getTools() and OpenAPI-based methods - Update Quick Start to use fetchTools() with async/await - Update AI SDK, OpenAI, and MCP integration examples - Add meta tools documentation for dynamic tool discovery - Remove deprecated configuration sections - Simplify authentication documentation BREAKING CHANGE: Documentation now only covers the fetchTools() API. The deprecated getTools() and OpenAPIToolSet APIs are no longer documented.

pkg-pr-new · 2025-12-05T14:46:48Z

Open in StackBlitz

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

commit: 84d7750

Copilot

Pull request overview

This PR removes all deprecated OpenAPI Specification (OAS) based tool generation infrastructure and migrates exclusively to the MCP-based fetchTools() API. This is a significant breaking change that simplifies the codebase by removing over 8,000 lines of code related to OAS parsing, generated specifications, and associated tooling.

Key changes:

Removed getTools(), getTool(), loadTools(), and getStackOneTools() methods
Deleted OpenAPIToolSet class and all OpenAPI parser/loader infrastructure
Removed src/openapi/ directory entirely (parser, loader, generated specs, tests)
Updated all examples and tests to use fetchTools() API
Removed build hooks for OAS-generated code cleanup

Reviewed changes

Copilot reviewed 33 out of 48 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tsdown.config.ts	Removed build hooks for cleaning up OAS-generated sourcemaps
src/toolsets/tests/stackone.spec.ts	Removed OAS-based tests, updated to test only MCP configuration
src/toolsets/tests/stackone.mcp-fetch.spec.ts	Updated test expectations to account for feedback tool inclusion
src/toolsets/tests/openapi.spec.ts	Deleted entire OAS toolset test file
src/toolsets/tests/fixtures/petstore.json	Deleted test fixture for OAS parsing
src/toolsets/tests/base.spec.ts	Removed tests for deprecated `getTools()` method
src/toolsets/stackone.ts	Removed OAS loading methods, kept only `fetchTools()`
src/toolsets/openapi.ts	Deleted entire OAS toolset implementation
src/toolsets/index.ts	Removed OpenAPI toolset exports
src/toolsets/base.ts	Removed `getTools()`, `getTool()`, and `tools` property
src/tests/exports.spec.ts	Updated to check for `BaseTool` and `createFeedbackTool` instead of OAS exports
src/openapi/*	Deleted parser, loader, and all generated specifications
src/index.ts	Removed OpenAPI-related exports
src/constants.ts	Removed `SPECS` array, updated comment spelling to British English
scripts/fetch-specs.ts	Deleted OAS fetching script
package.json	Removed `fetch:specs`, `rebuild`, and `test:scripts` commands
examples/*	Updated to use `fetchTools()` API, deleted OAS-specific examples

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-12-05T14:49:17Z

src/constants.ts

 *
 * - alpha=0.2 means: 20% BM25 + 80% TF-IDF
- * - This value was optimized through validation testing
+ * - This value was optimised through validation testing


The comment uses British English spelling "optimised" while other parts of the codebase use American English spelling "optimized". For consistency, this should use "optimized" to match the original.

Suggested change

* - This value was optimised through validation testing

* - This value was optimized through validation testing

Copilot · 2025-12-05T14:49:17Z

src/constants.ts

+ * - Lower values favour BM25 scoring (better keyword matching)
+ * - Higher values favour TF-IDF scoring (better semantic matching)


The comment uses British English spelling "favour" while other parts of the codebase use American English spelling "favor". For consistency, this should use "favor".

Suggested change

* - Lower values favour BM25 scoring (better keyword matching)

* - Higher values favour TF-IDF scoring (better semantic matching)

* - Lower values favor BM25 scoring (better keyword matching)

* - Higher values favor TF-IDF scoring (better semantic matching)

cubic-dev-ai

No issues found across 48 files

glebedel · 2025-12-08T11:48:11Z

examples/ai-sdk-integration.ts

+  // Initialise StackOne
+  const toolset = new StackOneToolSet({
+    accountId: ACCOUNT_IDS.HRIS,
+    baseUrl: process.env.STACKONE_BASE_URL ?? 'https://api.stackone.com',


is this a required parameter? we should just use default. I don't want to expose this baseUrl if we don't have to - it seems only relevant to our internal teams

it's required actually.
we gonna fix it in other pr

#149
i'll do it later

glebedel · 2025-12-08T11:48:32Z

examples/ai-sdk-integration.ts

  // Use max steps to automatically call the tool if it's needed
  const { text } = await generateText({
-    model: openai('gpt-5'),
+    model: openai('gpt-4o'),


should we do something more recent?

oh bad, it's vibe coded...

@glebedel we have lots of gpt-4 models including examles and readme, i'll do it in another PR

glebedel · 2025-12-08T12:54:42Z

examples/openai-integration.ts

+import process from 'node:process';
 import OpenAI from 'openai';
 import { StackOneToolSet } from '../src';
 import { ACCOUNT_IDS } from './constants';


I don't think it makes sense to ever have account_ids in constants vs fetching them from some kind of function or just setting them inline for the purpose of having examples, eg const accountId =

So they have already been implemented before. This PR just deletes all traditional getTools, so it should be dealt with in another PR.

we need to create another pr for it

glebedel · 2025-12-08T12:56:26Z

examples/human-in-the-loop.ts

+const isPlaceholderKey = !apiKey || apiKey === 'test-stackone-key';
+const shouldSkip = process.env.SKIP_FETCH_TOOLS_EXAMPLE !== '0' && isPlaceholderKey;
+


It seems that this should be a a per tool configuration rather than a based on an env variable

actually it is not my implementation. SKIP_FETCH_TOOLS_EXAMPLE is already there. i gonna create another example.

https://github.com/StackOneHQ/stackone-ai-node/tree/feat/migrate-to-pnpm-vitest
i'm working on getting rid of this "anti pattern of env variable usage" in this branch, so i gonna fix it soon.

ryoppippi · 2025-12-08T13:04:39Z

@glebedel Overall, the aim of this PR is to get rid of the getTools implementation and related tests. We need to do more stuff later:

Bun -> pnpm for reliability
Bun test -> vitest (for isolated process, environment mock, and network mock by MSW)
GPT-4 -> GPT-5
Fix examples
Remove environment variables as much as possible

In this PR, we keep the existing behavior. We should fix them in separate PRs.

glebedel

LGTM

@glebedel

…ders Remove the centralised constants.ts file containing hardcoded account IDs and replace with inline placeholder values in each example file. This change addresses feedback from PR #148 review by @glebedel: - Account IDs should not be stored in shared constants - Examples are clearer with inline values that users replace directly - Avoids exposing internal implementation details Changes: - Delete examples/constants.ts with hardcoded account IDs - Update all example files to use inline placeholder accountId variables - Each example now has a clear comment: "Replace with your actual account ID" - Update README.md to reflect new pattern and remove constants.ts references Closes #196

@glebedel

…ders (#198) Remove the centralised constants.ts file containing hardcoded account IDs and replace with inline placeholder values in each example file. This change addresses feedback from PR #148 review by @glebedel: - Account IDs should not be stored in shared constants - Examples are clearer with inline values that users replace directly - Avoids exposing internal implementation details Changes: - Delete examples/constants.ts with hardcoded account IDs - Update all example files to use inline placeholder accountId variables - Each example now has a clear comment: "Replace with your actual account ID" - Update README.md to reflect new pattern and remove constants.ts references Closes #196

ryoppippi added 13 commits December 5, 2025 14:42

ci: remove OpenAPI spec update check workflow

b1d18ab

Remove the GitHub Actions workflow that checked for OpenAPI spec updates. This workflow is no longer needed as the SDK no longer bundles pre-generated OpenAPI specifications.

chore(build): remove OAS sourcemap cleanup from tsdown config

abf4e0a

Remove the onSuccess hook that cleaned up sourcemap files for the generated OpenAPI spec files. This cleanup step is no longer needed as the OAS generated files have been removed from the codebase.

Copilot AI review requested due to automatic review settings December 5, 2025 14:46

ryoppippi requested a review from a team as a code owner December 5, 2025 14:46

Copilot started reviewing on behalf of ryoppippi December 5, 2025 14:47 View session

Copilot finished reviewing on behalf of ryoppippi December 5, 2025 14:47

Copilot AI reviewed Dec 5, 2025

View reviewed changes

cubic-dev-ai bot reviewed Dec 5, 2025

View reviewed changes

ryoppippi mentioned this pull request Dec 5, 2025

feat!: remove deprecated OAS-based getTools, migrate to fetchTools only StackOneHQ/stackone-ai-python#42

Merged

4 tasks

ryoppippi changed the title ~~refactor: remove deprecated OAS-based getTools, migrate to fetchTools only~~ feat!: remove deprecated OAS-based getTools, migrate to fetchTools only Dec 8, 2025

glebedel reviewed Dec 8, 2025

View reviewed changes

ryoppippi requested a review from glebedel December 8, 2025 12:19

glebedel reviewed Dec 8, 2025

View reviewed changes

ryoppippi requested a review from glebedel December 8, 2025 12:59

glebedel approved these changes Dec 8, 2025

View reviewed changes

ryoppippi merged commit aea526e into main Dec 8, 2025
42 checks passed

ryoppippi deleted the refactor/remove-oas-gettools branch December 8, 2025 17:53

github-actions bot mentioned this pull request Dec 8, 2025

chore(main): release 2.0.0 #150

Merged

This was referenced Dec 9, 2025

Refactor: Remove account_ids from constants, use inline values in examples #196

Closed

Refactor: Replace SKIP_FETCH_TOOLS_EXAMPLE env variable with per-tool configuration #197

Closed

ryoppippi mentioned this pull request Dec 9, 2025

refactor(examples): replace ACCOUNT_IDS constant with inline placeholders #198

Merged

3 tasks

This was referenced Dec 11, 2025

chore(main): release 0.3.0 #214

Closed

chore(main): release 0.3.0 #227

Closed

chore(main): release 2.0.0 #231

Merged

	* - This value was optimised through validation testing
	* - This value was optimized through validation testing

		* - Lower values favour BM25 scoring (better keyword matching)
		* - Higher values favour TF-IDF scoring (better semantic matching)

		const isPlaceholderKey = !apiKey \|\| apiKey === 'test-stackone-key';
		const shouldSkip = process.env.SKIP_FETCH_TOOLS_EXAMPLE !== '0' && isPlaceholderKey;

feat!: remove deprecated OAS-based getTools, migrate to fetchTools only #148

feat!: remove deprecated OAS-based getTools, migrate to fetchTools only #148

Uh oh!

Conversation

ryoppippi commented Dec 5, 2025 • edited by cubic-dev-ai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Breaking Changes

Changes

Migration

Test plan

Summary by cubic

Uh oh!

pkg-pr-new bot commented Dec 5, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ryoppippi commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

glebedel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ryoppippi commented Dec 5, 2025 •

edited by cubic-dev-ai bot

Loading

ryoppippi commented Dec 8, 2025 •

edited

Loading