docs: add CONTRIBUTING.md, split issue templates, update PR checklist

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -0,0 +1,63 @@
+name: Bug Report
+description: Report a bug or unexpected behavior
+title: "[Bug] <brief summary>"
+labels: [bug, needs-triage]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: A clear description of the bug.
+      placeholder: "The tool returned an error when..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      placeholder: |
+        1. Configure the MCP server with ...
+        2. Ask the AI assistant to ...
+        3. Observe ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      placeholder: "The tool should have returned..."
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: Output of `npx @mapbox/mcp-server --version` or package version
+      placeholder: "0.4.7"
+    validations:
+      required: false
+
+  - type: dropdown
+    id: client
+    attributes:
+      label: MCP Client
+      description: Which AI assistant or MCP client are you using?
+      options:
+        - Claude Desktop
+        - Claude Code
+        - Cursor
+        - VS Code (GitHub Copilot)
+        - Other
+    validations:
+      required: false
+
+  - type: textarea
+    id: notes
+    attributes:
+      label: Additional Context
+      description: Logs, screenshots, or anything else that might help.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/feature_request.yaml

@@ -0,0 +1,42 @@
+name: Feature Request
+description: Suggest a new tool, resource, prompt, or improvement
+title: "[Feature] <brief summary>"
+labels: [enhancement, needs-triage]
+body:
+  - type: dropdown
+    id: type
+    attributes:
+      label: Type
+      options:
+        - New tool
+        - New resource
+        - New prompt
+        - Improvement to existing tool/resource
+        - Documentation
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or Motivation
+      description: What use case or gap does this address?
+      placeholder: "When I ask Claude to..., there's no good way to..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed Solution
+      description: What should the new tool/resource/prompt do?
+    validations:
+      required: true
+
+  - type: textarea
+    id: notes
+    attributes:
+      label: Additional Context
+    validations:
+      required: false

.github/pull_request_template.md

@@ -14,9 +14,10 @@
 
 ## Checklist
 
-- [ ] Code has been tested locally
-- [ ] Unit tests have been added or updated
-- [ ] Documentation has been updated if needed
+- [ ] Tests added or updated (`npm test` passes)
+- [ ] Lint passes (`npm run lint`)
+- [ ] `CHANGELOG.md` updated under `Unreleased`
+- [ ] Documentation updated if needed (README, JSDoc)
 
 ---
 

CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# Contributing to Mapbox MCP Server
+
+Thank you for your interest in contributing! Please read this guide before submitting a pull request.
+
+## Getting Started
+
+```bash
+git clone https://github.com/mapbox/mcp-server.git
+cd mcp-server
+npm install
+npm test
+```
+
+A Mapbox access token with appropriate scopes is required for most tools. Set `MAPBOX_ACCESS_TOKEN` in your environment.
+
+## Pull Requests
+
+- Keep PRs small and focused on a single change
+- **Always update `CHANGELOG.md`** — add your entry under the `Unreleased` section with the PR number
+- All CI checks must pass before merging (lint, format, tests)
+- At least one maintainer approval is required
+
+## Standards & Guidelines
+
+| Document                                                             | Contents                                                                   |
+| -------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| [docs/engineering_standards.md](./docs/engineering_standards.md)     | Complete code quality, testing, documentation, and collaboration standards |
+| [CLAUDE.md](./CLAUDE.md)                                             | Patterns and workflows for contributors using Claude Code                  |
+| [AGENTS.md](./AGENTS.md)                                             | Guide for other AI coding assistants (Cursor, Continue, Aider, etc.)       |
+| [.github/copilot-instructions.md](./.github/copilot-instructions.md) | GitHub Copilot guidelines                                                  |
+
+## Quick Reference
+
+### Creating a New Tool
+
+```bash
+# Interactive (requires a TTY):
+npx plop create-tool
+
+# Non-interactive (for AI agents and CI):
+npx plop create-tool "ToolName" "tool_name_tool"
+```
+
+### Before Committing
+
+```bash
+npm test            # All tests must pass
+npm run lint        # ESLint (auto-fixed by pre-commit hook)
+npm run format      # Prettier (auto-fixed by pre-commit hook)
+```
+
+### Changelog Format
+
+```markdown
+## Unreleased
+
+### Features Added
+
+- **My Feature**: Description of what changed and why (#PR_NUMBER)
+```
+
+## Security
+
+- Never commit API keys or tokens — use environment variables
+- Run `npm audit` if you add or update dependencies

README.md

@@ -544,12 +544,15 @@ See [docs/tracing.md](./docs/tracing.md) for complete setup instructions includi
 
 ## Contributing
 
-We welcome contributions to the Mapbox MCP Server! Please review our standards and guidelines before contributing:
+We welcome contributions to the Mapbox MCP Server! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) before submitting a pull request.
 
-- **[Engineering Standards (docs/engineering_standards.md)](./docs/engineering_standards.md)** - Complete code quality, testing, documentation, and collaboration standards for all contributors
+Full standards and guidelines:
+
+- **[CONTRIBUTING.md](./CONTRIBUTING.md)** - Getting started, PR process, quick reference
+- **[Engineering Standards (docs/engineering_standards.md)](./docs/engineering_standards.md)** - Complete code quality, testing, documentation, and collaboration standards
 - **[Claude Code Guide (CLAUDE.md)](./CLAUDE.md)** - Standards and patterns for contributors using Claude Code
-- **[AI Agent Instructions (AGENTS.md)](./AGENTS.md)** - Guide for general AI coding assistants (Cursor, Continue, Aider, etc.)
-- **[GitHub Copilot Guidelines](./.github/copilot-instructions.md)** - Best practices for using GitHub Copilot responsibly in this project
+- **[AI Agent Instructions (AGENTS.md)](./AGENTS.md)** - Guide for other AI coding assistants (Cursor, Continue, Aider, etc.)
+- **[GitHub Copilot Guidelines](./.github/copilot-instructions.md)** - Best practices for using GitHub Copilot responsibly
 
 ### Quick Start for Contributors