Add automated CHANGELOG release preparation script

Created scripts/prepare-changelog-release.cjs to automate
CHANGELOG updates during releases:
- Replaces "Unreleased" with version number and date
- Adds new empty "Unreleased" section at top
- Validates version format and CHANGELOG structure
- Added as npm script: changelog:prepare-release

Updated CLAUDE.md with release process documentation
showing how to use the new script.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: mattpodwysocki

CHANGELOG.md

@@ -7,6 +7,14 @@
   - Document what changed, why, and any breaking changes
   - Add entry under "Unreleased" section with PR number
 
+### Developer Experience
+
+- **Release Process**: Added automated CHANGELOG preparation script (#112)
+  - New `npm run changelog:prepare-release <version>` command
+  - Automatically replaces "Unreleased" with version and date
+  - Adds new empty "Unreleased" section for next changes
+  - Includes validation for version format and CHANGELOG structure
+
 ## 0.8.3
 
 ### Security

CLAUDE.md

@@ -91,6 +91,27 @@ When creating pull requests:
 - Add your entry under the "Unreleased" section at the top
 - Include the PR number and a brief description of the change
 
+### Release Process
+
+When preparing a new release:
+
+```bash
+# Prepare CHANGELOG for release (replaces "Unreleased" with version and date)
+npm run changelog:prepare-release 1.0.0
+
+# Review changes, then commit and tag
+git add CHANGELOG.md
+git commit -m "Release v1.0.0"
+git tag v1.0.0
+git push && git push --tags
+```
+
+The `changelog:prepare-release` script automatically:
+
+- Replaces "## Unreleased" with "## {version} - {date}"
+- Adds a new empty "## Unreleased" section at the top
+- Validates version format and CHANGELOG structure
+
 ## Important Constraints
 
 - **Dependency Injection**: Tools must accept `httpRequest` parameter for testability

PR_DESCRIPTION.md

@@ -0,0 +1,134 @@
+# Add explicit subpath exports (alternative to #110)
+
+## 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
+
+```typescript
+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
+
+```typescript
+import { DirectionsTool } from '@mapbox/mcp-server/tools';
+import { httpRequest } from '@mapbox/mcp-server/utils';
+
+const tool = new DirectionsTool({ httpRequest });
+```
+
+### Expert: Full customization
+
+```typescript
+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:
+
+```typescript
+import { getCoreTools } from '@mapbox/mcp-server/tools';
+import { httpRequest } from '@mapbox/mcp-server/utils';
+```
+
+Let me know if this works for your use case!

package.json

@@ -11,6 +11,7 @@
   },
   "scripts": {
     "build": "npm run prepare && tshy && npm run generate-version && node scripts/add-shebang.cjs",
+    "changelog:prepare-release": "node scripts/prepare-changelog-release.cjs",
     "format": "prettier --check \"./src/**/*.{ts,tsx,js,json,md}\" \"./test/**/*.{ts,tsx,js,json,md}\"",
     "format:fix": "prettier --write \"./src/**/*.{ts,tsx,js,json,md}\" \"./test/**/*.{ts,tsx,js,json,md}\"",
     "generate-version": "node scripts/build-helpers.cjs generate-version",

scripts/prepare-changelog-release.cjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// Copyright (c) Mapbox, Inc.
+// Licensed under the MIT License.
+
+/**
+ * Prepares CHANGELOG.md for a new release by:
+ * 1. Replacing "## Unreleased" with "## {version}"
+ * 2. Adding current date to the version heading
+ * 3. Adding a new empty "## Unreleased" section at the top
+ *
+ * Usage:
+ *   node scripts/prepare-changelog-release.cjs <version>
+ *   npm run changelog:prepare-release <version>
+ *
+ * Example:
+ *   node scripts/prepare-changelog-release.cjs 1.0.0
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const process = require('node:process');
+
+function prepareChangelogRelease(version) {
+  if (!version) {
+    console.error('Error: Version number is required');
+    console.error('Usage: node scripts/prepare-changelog-release.cjs <version>');
+    process.exit(1);
+  }
+
+  // Validate version format (basic semver check)
+  if (!/^\d+\.\d+\.\d+(-[a-zA-Z0-9.-]+)?$/.test(version)) {
+    console.error(`Error: Invalid version format: ${version}`);
+    console.error('Expected format: X.Y.Z or X.Y.Z-prerelease');
+    process.exit(1);
+  }
+
+  const changelogPath = path.join(process.cwd(), 'CHANGELOG.md');
+
+  // Check if CHANGELOG.md exists
+  if (!fs.existsSync(changelogPath)) {
+    console.error('Error: CHANGELOG.md not found');
+    process.exit(1);
+  }
+
+  // Read CHANGELOG.md
+  const content = fs.readFileSync(changelogPath, 'utf8');
+
+  // Check if "## Unreleased" exists
+  if (!content.includes('## Unreleased')) {
+    console.error('Error: No "## Unreleased" section found in CHANGELOG.md');
+    console.error('Nothing to release - add changes under "## Unreleased" first');
+    process.exit(1);
+  }
+
+  // Get current date in YYYY-MM-DD format
+  const date = new Date().toISOString().split('T')[0];
+
+  // Replace "## Unreleased" with "## {version} - {date}"
+  // and add a new "## Unreleased" section at the top
+  const updatedContent = content.replace(
+    '## Unreleased',
+    `## Unreleased\n\n## ${version} - ${date}`
+  );
+
+  // Write updated content back to CHANGELOG.md
+  fs.writeFileSync(changelogPath, updatedContent, 'utf8');
+
+  console.log(`✓ CHANGELOG.md updated successfully`);
+  console.log(`  - Released version ${version} (${date})`);
+  console.log(`  - Added new "Unreleased" section`);
+  console.log('');
+  console.log('Next steps:');
+  console.log('  1. Review CHANGELOG.md');
+  console.log('  2. Commit changes: git add CHANGELOG.md && git commit -m "Release v' + version + '"');
+  console.log('  3. Create tag: git tag v' + version);
+  console.log('  4. Push: git push && git push --tags');
+}
+
+// Process command line arguments
+const version = process.argv[2];
+prepareChangelogRelease(version);