refactor(tools): harness-agnostic tool definitions

AGENTS.md

@@ -11,7 +11,7 @@ make-sdk/
 ├── src/
 │   ├── endpoints/            # API endpoint implementations
 │   │   ├── *.ts              # Endpoints
-│   │   └── *.mcp.ts          # MCP Tools
+│   │   └── *.tools.ts        # Tool definitions (MCP / CLI / …)
 │   ├── index.ts              # Main entry point with all exports
 │   ├── make.ts               # Core Make client class
 │   ├── types.ts              # Common type definitions
@@ -518,13 +518,13 @@ export type ListEntityNamesOptions<C extends keyof EntityName = never> = {
 };
 ```
 
-## MCP (Model Context Protocol) Integration
+## Tool Definitions
 
-The Make TypeScript SDK supports MCP tool integration to provide AI agents with access to all SDK functionality. This section covers the patterns and conventions for creating MCP tool definitions.
+Every endpoint ships with a companion **tool definitions** file that describes its operations in a harness-agnostic shape. The same definitions power the MCP server (`@makehq/sdk/mcp`), the Make CLI, and any other integration that wants a uniform view of SDK operations — nothing here is specific to MCP. This section covers the patterns and conventions for creating those definitions.
 
-### MCP File Structure
+### Tool Definitions File Structure
 
-**File Location**: `src/endpoints/{endpoint-name}.mcp.ts` or `src/endpoints/sdk/{endpoint-name}.mcp.ts`
+**File Location**: `src/endpoints/{endpoint-name}.tools.ts` or `src/endpoints/sdk/{endpoint-name}.tools.ts`
 
 ```typescript
 import type { Make } from '../../make.js';
@@ -553,7 +553,7 @@ export const tools = [
 
 ### Import Patterns
 
-**Always use type imports** for MCP files since they only reference types:
+**Always use type imports** for tool definition files since they only reference types:
 
 ```typescript
 // ✅ Correct - Type imports only
@@ -724,11 +724,11 @@ export const tools = [
 ];
 ```
 
-### MCP Integration Checklist
+### Tool Definitions Checklist
 
-Before completing MCP tool definitions:
+Before completing tool definitions:
 
-- [ ] File uses `.mcp.ts` extension
+- [ ] File uses `.tools.ts` extension
 - [ ] Uses `type` imports only (no runtime imports)
 - [ ] All tools follow the exact naming convention
 - [ ] Categories are properly hierarchical
@@ -738,8 +738,9 @@ Before completing MCP tool definitions:
 - [ ] TypeScript types match the actual SDK method signatures
 - [ ] Descriptions are clear and helpful
 - [ ] All public SDK methods are covered
+- [ ] New file is registered in `src/tools.ts` (the aggregator consumed by both `./tools` and `./mcp` exports)
 
-### Common MCP Mistakes to Avoid
+### Common Tool Definition Mistakes to Avoid
 
 1. **Using runtime imports** - Always use `type` imports only
 2. **Incorrect parameter extraction** - Ensure body parameters are properly separated
@@ -748,8 +749,9 @@ Before completing MCP tool definitions:
 5. **Wrong categories** - Use kebab-case for all categories, including SDK (e.g., `sdk-apps`, not `sdk.apps`)
 6. **Missing descriptions** - Every parameter and tool needs clear documentation
 7. **Type mismatches** - Ensure TypeScript types match actual SDK signatures
-8. **Incomplete coverage** - All public methods should have corresponding MCP tools
+8. **Incomplete coverage** - All public methods should have corresponding tool definitions
+9. **Forgetting to register in `src/tools.ts`** - A new `*.tools.ts` file is only live once its `tools` array is spread into `MakeTools`
 
-This MCP integration ensures that AI agents can access the full Make SDK functionality through a standardized protocol interface while maintaining type safety and clear documentation.
+These tool definitions ensure that AI agents, CLIs, and other harnesses can access the full Make SDK functionality through a standardized shape while maintaining type safety and clear documentation.
 
 This guide ensures consistent, maintainable, and well-tested extensions to the Make TypeScript SDK.

README.md

@@ -80,7 +80,7 @@ const make = new Make('your-api-key', 'eu2.make.com', {
 - Support for majority of Make API endpoints
 - Built-in error handling and response typing
 - Comprehensive test coverage
-- Model Context Protocol (MCP) support
+- Harness-agnostic tool definitions powering the [Make MCP Server](https://developers.make.com/mcp-server) and the [Make CLI](https://github.com/integromat/make-cli)
 
 ## Configuration Options
 
@@ -124,21 +124,24 @@ The SDK supports automatic retries with exponential backoff for handling rate li
 
 The retry mechanism uses exponential backoff with jitter to prevent thundering herd problems. When a `Retry-After` header is present in the response, the SDK respects it (capped at `maxDelay`).
 
-## MCP Server Support
+## Tool Definitions
 
-This SDK includes full support for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), allowing AI agents to interact with the Make API through standardized tools. All SDK endpoints are automatically exposed as MCP tools.
+Every SDK endpoint is also described as a harness-agnostic **tool definition** - a self-contained record with a JSON Schema, examples, and an executor. The same definitions power:
 
-### Integrating with MCP Server (experimental)
+- the official [Make MCP Server](https://developers.make.com/mcp-server),
+- the official [Make CLI](https://github.com/integromat/make-cli),
+- and any future consumer.
+
+Import them directly via the `./tools` subpath:
 
 ```ts
 import { Make } from '@makehq/sdk';
-import { MakeMCPTools } from '@makehq/sdk/mcp';
+import { MakeTools } from '@makehq/sdk/tools';
 
-// Initialize the Make client
 const make = new Make('your-api-key', 'eu2.make.com');
 
 // List tools
-const tools = MakeMCPTools.map(tool => {
+const tools = MakeTools.map(tool => {
     return {
         name: tool.name,
         title: tool.title,
@@ -147,8 +150,8 @@ const tools = MakeMCPTools.map(tool => {
     };
 });
 
-// Execute tool
-const tool = MakeMCPTools.find(tool => tool.name === 'scenarios_list');
+// Execute a tool
+const tool = MakeTools.find(tool => tool.name === 'scenarios_list');
 
 try {
     await tool.execute(make, { teamId: 1 });
@@ -221,9 +224,10 @@ make-sdk/
 ├── src/                       # Source code
 │   ├── endpoints/             # API endpoint implementations
 │   │   ├── *.ts               # Endpoints
-│   │   └── *.mcp.ts           # MCP Tools
+│   │   └── *.tools.ts         # Tool definitions (MCP / CLI / …)
 │   ├── index.ts               # Main entry point
 │   ├── make.ts                # Core Make client
+│   ├── tools.ts               # Aggregated tool definitions (./tools export)
 │   ├── types.ts               # Common type definitions
 │   └── utils.ts               # Utility functions
 ├── test/                      # Test files

package.json

@@ -1,6 +1,6 @@
 {
     "name": "@makehq/sdk",
-    "version": "1.2.1",
+    "version": "1.3.0",
     "description": "Make TypeScript SDK",
     "license": "MIT",
     "author": "Make",
@@ -35,6 +35,16 @@
                 "default": "./dist/index.cjs"
             }
         },
+        "./tools": {
+            "import": {
+                "types": "./dist/tools.d.ts",
+                "default": "./dist/tools.js"
+            },
+            "require": {
+                "types": "./dist/tools.d.cts",
+                "default": "./dist/tools.cjs"
+            }
+        },
         "./mcp": {
             "import": {
                 "types": "./dist/mcp.d.ts",

scripts/run-mcp-server.mjs

@@ -7,7 +7,7 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { Make } from '../dist/index.js';
-import { MakeMCPTools } from '../dist/mcp.js';
+import { MakeTools } from '../dist/tools.js';
 
 const server = new Server(
     {
@@ -34,7 +34,7 @@ const make = new Make(process.env.MAKE_API_KEY, process.env.MAKE_ZONE);
 
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     return {
-        tools: MakeMCPTools.map(tool => {
+        tools: MakeTools.map(tool => {
             return {
                 name: tool.name,
                 title: tool.title,
@@ -46,7 +46,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 });
 
 server.setRequestHandler(CallToolRequestSchema, async request => {
-    const tool = MakeMCPTools.find(tool => tool.name === request.params.name);
+    const tool = MakeTools.find(tool => tool.name === request.params.name);
     if (!tool) {
         throw new Error(`Unknown tool: ${request.params.name}`);
     }

src/endpoints/connections.mcp.ts → src/endpoints/connections.tools.ts

@@ -8,6 +8,7 @@ export const tools = [
         description: 'List connections for a team.',
         category: 'connections',
         scope: 'connections:read',
+        scopeId: 'teamId',
         identifier: 'teamId',
         annotations: {
             readOnlyHint: true,
@@ -46,7 +47,9 @@ export const tools = [
         description: 'Get details of a specific connection.',
         category: 'connections',
         scope: 'connections:read',
+        scopeId: 'connectionId',
         identifier: 'connectionId',
+        resourceId: 'connectionId',
         annotations: {
             readOnlyHint: true,
         },
@@ -68,6 +71,7 @@ export const tools = [
         description: 'Create a new connection.',
         category: 'connections',
         scope: 'connections:write',
+        scopeId: 'teamId',
         identifier: 'teamId',
         annotations: {
             idempotentHint: true,
@@ -109,7 +113,9 @@ export const tools = [
         description: "Update a connection's configuration data.",
         category: 'connections',
         scope: 'connections:write',
+        scopeId: 'connectionId',
         identifier: 'connectionId',
+        resourceId: 'connectionId',
         annotations: {
             idempotentHint: true,
             destructiveHint: true,
@@ -143,7 +149,9 @@ export const tools = [
         description: 'Verify if a connection is working correctly.',
         category: 'connections',
         scope: 'connections:write',
+        scopeId: 'connectionId',
         identifier: 'connectionId',
+        resourceId: 'connectionId',
         annotations: {
             idempotentHint: true,
             destructiveHint: false,
@@ -168,7 +176,9 @@ export const tools = [
         description: 'Delete a connection.',
         category: 'connections',
         scope: 'connections:write',
+        scopeId: 'connectionId',
         identifier: 'connectionId',
+        resourceId: 'connectionId',
         annotations: {
             destructiveHint: true,
         },