tools

Tool Development Patterns

Factory Pattern

Every tool exports a factory function registered in src/tools/tools.ts:

export const getMyTool = (server: Server): Tool<typeof paramsSchema> => {
  const myTool = new Tool({
    server,
    name: 'my-tool',           // Must be in ToolName union (src/tools/toolName.ts)
    description: '...',
    paramsSchema,               // Zod schema object (not z.object, just raw shape)
    annotations: { title: 'My Tool', readOnlyHint: true, openWorldHint: false },
    callback: async (args, extra) => { ... },
  });
  return myTool;
};

Adding a New Tool — Checklist

1. Add tool name to toolNames array in src/tools/toolName.ts
2. Add to appropriate toolGroups entry (or create new group)
3. Add scope mapping in src/server/oauth/scopes.ts (toolScopeMap)
4. Create tool directory under src/tools/
5. Implement factory function following the pattern above
6. Register factory in src/tools/tools.ts (toolFactories array)

Tool Callback Pattern

Callbacks use logAndExecute from the base Tool class:

callback: async (args, extra): Promise<CallToolResult> => {
  return await myTool.logAndExecute({
    extra,
    args,
    callback: async () => {
      const result = await useRestApi({
        ...extra,
        jwtScopes: myTool.requiredApiScopes,
        callback: async (restApi) => {
          // Use restApi methods here
          return data;
        },
      });
      return new Ok(result);     // ts-results-es Ok()
    },
    constrainSuccessResult: (result) => constrainMyResult(result),
  });
},

Result Types

• Result<T, E> from ts-results-es — tool callbacks return this
• Ok(value) for success, Err(error) for typed errors
• ConstrainedResult<T> — post-processing step with three outcomes:
  • { type: 'success', result: T } — data returned to client
  • { type: 'empty', message: string } — no data found (not an error)
  • { type: 'error', message: string, error?: Error } — logical error