Reorganize documentation and prepare v1.0.0-2 release

- Reorganized README.md structure: Quick Start → MCP Integration → Available Tools → Features
- Moved developer documentation to docs/ folder:
  - docs/DEVELOPMENT.md - Development workflow and contributing guidelines
  - docs/API-UPDATES.md - API synchronization procedures
  - docs/TROUBLESHOOTING.md - Common issues and solutions
- Added Claude Code .mcp.json configuration support
- Added Nix flake direct execution from GitHub
- Fixed flake.nix executable wrapper for ES modules
- Added npm publishing workflow and configuration
- Enhanced test coverage for v1.0.0-2 release

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: gui-wf

.github/workflows/npm-publish.yml

@@ -0,0 +1,57 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to publish (patch/minor/major)'
+        required: true
+        default: 'patch'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Nix
+        uses: DeterminateSystems/nix-installer-action@main
+
+      - name: Setup Nix Cache
+        uses: DeterminateSystems/magic-nix-cache-action@main
+
+      - name: Enter Nix Development Shell and Install Dependencies
+        run: nix develop --command npm ci
+
+      - name: Build Package
+        run: nix develop --command npm run build
+
+      - name: Test Package
+        run: nix develop --command npm run test:mock
+
+      - name: Version Bump (if manual trigger)
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          nix develop --command npm version ${{ github.event.inputs.version }} --no-git-tag-version
+          git config user.name "GitHub Actions"
+          git config user.email "[email protected]"
+          git add package.json package-lock.json
+          git commit -m "chore: bump version to $(node -p "require('./package.json').version")"
+          git push
+
+      - name: Publish to npm
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: nix run .#npm-publish
+
+      - name: Create GitHub Tag (if manual trigger)
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          git tag "v$VERSION"
+          git push origin "v$VERSION"

.npmignore

@@ -0,0 +1,50 @@
+# Source files (only distribute built files)
+src/
+scripts/
+.claude/
+.github/
+docs/
+nix/
+
+# Development files
+*.test.ts
+*.spec.ts
+vitest.config.ts
+tsconfig.json
+.eslintrc*
+.prettierrc*
+
+# Nix files
+flake.nix
+flake.lock
+*.nix
+
+# Git files
+.git/
+.gitignore
+
+# Editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Environment files
+.env*
+.npmrc
+
+# MCP config
+.mcp.json
+
+# Logs
+*.log
+npm-debug.log*
+
+# Dependencies
+node_modules/
+
+# Build artifacts not needed
+*.map
+
+# Documentation that's not needed in package
+LICENSE_COMPARISON.md

.npmrc

@@ -0,0 +1 @@
+//registry.npmjs.org/:_authToken=${NPM_TOKEN}

CLAUDE.md

@@ -24,6 +24,10 @@ MCP (Model Context Protocol) server for PurelyMail email service. Exposes Purely
 
 See `docs/KNOWN_ISSUES.md` for detailed documentation of current limitations and workarounds.
 
+## Release Management
+
+See `docs/versioning-guidelines.md` for semantic versioning practices and release procedures.
+
 ## Commands
 ```bash
 # Development
@@ -185,3 +189,27 @@ npm list --depth=0 --json | jq '.dependencies | to_entries[] | {name: .key, vers
 - ❓ **Unknown**: Undefined or unrecognized licenses
 
 **Always use `/check-license` first** - it contains the complete decision tree and will guide you through any scenario.
+
+## Security
+
+### API Key Management
+- Never commit API keys to version control
+- Use environment variables for sensitive configuration (`PURELYMAIL_API_KEY`)
+- Store API keys securely in CI/CD systems (GitHub secrets, etc.)
+
+### Development Safety
+- Mock mode is safe for development and testing
+- Use `MOCK_MODE=true` when possible to avoid real API calls
+- Test with MCP Inspector before connecting to production API
+
+### Code Security
+- Validate all inputs against swagger schemas
+- Sanitize error messages (no sensitive data)
+- Use type-safe generated client methods
+- Never expose raw API responses without validation
+- Review all changes to generated client code
+
+### MCP Server Security
+- The server uses stdio transport - only local connections
+- Environment variables are not logged or exposed
+- Error messages are filtered to prevent data leakage