Add explicit subpath exports (alternative to #110)

[mattpodwysocki]

Summary

This PR provides a better alternative to #110's wildcard export approach. Instead of "./*": "./*" which exposes the entire internal structure, this implements explicit, well-documented subpath exports.

Motivation

Addresses the need from #110 where users want to import parts of this package without the entire server. The wildcard approach in #110 has several drawbacks:

• Exposes all internal implementation details
• No control over public API surface
• Makes it harder to refactor internals without breaking users
• Not clear what's intended to be public vs private

Solution

Explicit subpath exports via tshy:

• @mapbox/mcp-server/tools - Tool classes and pre-configured instances
• @mapbox/mcp-server/resources - Resource classes and instances
• @mapbox/mcp-server/prompts - Prompt classes and instances
• @mapbox/mcp-server/utils - HTTP pipeline utilities

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

Usage Examples

Simple: Pre-configured instances

import { directions, searchAndGeocode, isochrone } from '@mapbox/mcp-server/tools';

// Ready to use - no configuration needed
const server = new McpServer({ name: 'my-server', version: '1.0.0' });
directions.installTo(server);

Advanced: Custom HTTP pipeline

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

const tool = new DirectionsTool({ httpRequest });

Expert: Full customization

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

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

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

Changes

New Files

• Barrel exports (src/{tools,resources,prompts,utils}/index.ts) - Clean public APIs
• Documentation (docs/importing-tools.md) - Comprehensive usage guide with examples
• Examples (examples/import-example.ts) - Working code demonstrating all patterns
• Tests (test/exports.test.ts) - Validates all subpath exports work correctly
• Config (tsconfig.examples.json) - Type checking for examples

Updated Files

• package.json - Added tshy exports config, updated lint/format scripts to include examples
• README.md - Added link to importing guide
• CLAUDE.md - Documented package exports

Benefits Over Wildcard Approach

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., directions instead of directionsTool)
7. ✅ Flexible - Three levels of usage (simple, advanced, expert)

Testing

• ✅ All 611 existing tests pass
• ✅ New test suite (test/exports.test.ts) validates all subpath exports
• ✅ Examples included in linting, formatting, and type checking
• ✅ Documentation includes working, type-checked examples
• ✅ Both ESM and CommonJS exports verified

Documentation

Comprehensive documentation added in docs/importing-tools.md covering:

• All usage patterns (simple to expert)
• Complete API reference
• Working examples for common scenarios
• Best practices

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

Related

Closes #110 (provides better alternative to wildcard exports)

---

@vincent-lecrubier-skydio This provides what you need from #110 but with a cleaner, more maintainable approach. You can now import just the tools you need:

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

Let me know if this works for your use case!