Add explicit subpath exports for tools, resources, prompts, and utils

[mattpodwysocki]

Summary

Implements explicit, well-documented subpath exports to allow users to import specific Mapbox MCP Devkit components without the full server. This follows the same pattern established in the main mcp-server package.

Motivation

Users may want to:

• Import only specific tools/resources/prompts they need
• Build custom MCP servers with a subset of devkit components
• Integrate devkit tools into their own applications
• Access the HTTP pipeline utilities for custom implementations

Solution

Explicit subpath exports via tshy:

• @mapbox/mcp-devkit-server/tools - 25 devkit tool classes and pre-configured instances
• @mapbox/mcp-devkit-server/resources - 8 resource classes and instances (including UI resources)
• @mapbox/mcp-devkit-server/prompts - 7 prompt classes and instances
• @mapbox/mcp-devkit-server/utils - HTTP pipeline utilities

All exports support both ESM and CommonJS automatically via tshy dual builds.

Usage Examples

Simple: Pre-configured instances

import { listStyles, createStyle, previewStyle } from '@mapbox/mcp-devkit-server/tools';

// Ready to use - httpRequest already configured
const server = new McpServer({ name: 'my-server', version: '1.0.0' });
listStyles.installTo(server);

Advanced: Custom HTTP pipeline

import { ListStylesTool } from '@mapbox/mcp-devkit-server/tools';
import { httpRequest } from '@mapbox/mcp-devkit-server/utils';

const tool = new ListStylesTool({ httpRequest });

Expert: Full customization

import { HttpPipeline, UserAgentPolicy, RetryPolicy } from '@mapbox/mcp-devkit-server/utils';
import { ListStylesTool } from '@mapbox/mcp-devkit-server/tools';

const pipeline = new HttpPipeline();
pipeline.usePolicy(new UserAgentPolicy('MyApp/2.0.0'));
pipeline.usePolicy(new RetryPolicy(5, 300, 5000));

const tool = new ListStylesTool({ httpRequest: pipeline.execute.bind(pipeline) });

Changes

New Files

• src/tools/index.ts (7.7KB) - Barrel export for all 25 devkit tools
• src/resources/index.ts (3.7KB) - Barrel export for all 8 resources
• src/prompts/index.ts (2.9KB) - Barrel export for all 7 prompts
• src/utils/index.ts (1.5KB) - Barrel export for HTTP utilities

Updated Files

• package.json - Added tshy exports configuration

Benefits

1. ✅ Explicit API surface - Only exports what's intended to be public
2. ✅ Better discoverability - Clear, documented entry points
3. ✅ Type safety - Full TypeScript support
4. ✅ Tree-shaking friendly - Bundlers can optimize imports better
5. ✅ Future-proof - Can evolve internals without breaking users
6. ✅ Clean names - Instance exports use short names (e.g., listStyles instead of listStylesTool)
7. ✅ Flexible - Three levels of usage (simple, advanced, expert)

Compatibility

• ✅ Backward compatible - doesn't affect existing usage
• ✅ Supports both ESM and CommonJS
• ✅ Works with all bundlers (webpack, rollup, esbuild, vite, etc.)
• ✅ Full TypeScript support with type definitions

Testing

• ✅ Build passes with new exports
• ✅ Both ESM and CommonJS exports generated correctly
• ✅ All existing tests should continue to pass

Related

Similar to the implementation in mapbox/mcp-server#111