[docs] Update CLAUDE and other agent docs (#76)

Author: mattpodwysocki

.github/copilot-instructions.md

@@ -1,57 +1,57 @@
-# GitHub Copilot Usage & Standards for Mapbox MCP Server
+# GitHub Copilot Guidelines for Mapbox MCP Server
 
-This document defines how to use GitHub Copilot effectively and responsibly in the Mapbox MCP server repository. Following these guidelines ensures Copilot is a productive tool that supports, but does not replace, our engineering standards.
+This document defines responsible use of GitHub Copilot in this repository. Copilot is a productivity tool that must work within our engineering standards.
 
----
+## Core Principles
 
-## 1. Copilot as an Assistant, Not an Authority
+### 1. Review, Don't Auto-Accept
 
-- **Review All Suggestions:** Never accept Copilot code without reviewing it for correctness, security, and style.
-- **Understand Before You Use:** Only use Copilot suggestions you fully understand. If unsure, ask for clarification or write it yourself.
-- **No Blind Copy-Paste:** Do not copy-paste large blocks of Copilot code without adapting to project context.
+- **Always review** Copilot suggestions before accepting
+- **Understand first** - only use code you fully comprehend
+- **No blind copy-paste** - adapt suggestions to project context
+- **Iterate** - use suggestions as starting points, not final solutions
 
----
+### 2. Security First
 
-## 2. Code Quality & Consistency
+- **Never accept** suggestions with hardcoded secrets, tokens, or credentials
+- **Review carefully** any code handling sensitive data
+- **Environment variables** - ensure secrets use `.env` files, never committed
 
-- **Follow Project Standards:** All Copilot-generated code must comply with the standards in `CLAUDE.md` and our linting, typing, and testing requirements.
-- **TypeScript Only:** Copilot suggestions must be in TypeScript for all code in `src/` and `test/`.
-- **No Global Pollution:** Do not accept suggestions that patch or override global objects (e.g., `global.fetch`).
+### 3. Quality Standards
 
----
+- All Copilot code must comply with standards in **CLAUDE.md** and **docs/engineering_standards.md**
+- Pre-commit hooks will enforce linting, formatting, and TypeScript strictness
+- If Copilot suggests patterns inconsistent with the codebase, reject and write manually
 
-## 3. Testing & Documentation
+### 4. Testing & Documentation
 
-- **Tests Required:** All Copilot-generated features or fixes must include appropriate unit tests.
-- **JSDoc & Comments:** Add or edit documentation/comments for Copilot code as you would for hand-written code.
-
----
+- Include unit tests for all Copilot-generated features or fixes
+- Add or update JSDoc comments as you would for hand-written code
+- Update README.md or CHANGELOG.md if user-facing changes
 
-## 4. Security & Privacy
+### 5. Collaboration
 
-- **No Secrets:** Never accept suggestions that include hardcoded secrets, tokens, or credentials.
-- **Sensitive Data:** Do not use Copilot to generate or handle sensitive data without review.
+- All Copilot code goes through standard PR review process
+- Mention in PR description if significant portion is Copilot-generated
+- Provide feedback if Copilot produces poor/unsafe suggestions
 
----
+## When to Avoid Copilot
 
-## 5. Collaboration & Review
+- **Critical business logic** - prefer hand-written code with thorough review
+- **Security-sensitive code** - authentication, authorization, data validation
+- **Legal/compliance code** - licensing, terms of service, privacy policies
+- **Architecture decisions** - let humans make strategic choices
 
-- **Pull Requests:** All Copilot-generated code must go through the standard PR review process.
-- **Attribution:** If a significant portion of a PR is Copilot-generated, mention it in the PR description.
-- **Feedback:** If Copilot produces poor or unsafe suggestions, provide feedback to improve future results.
+## Learning from the Codebase
 
----
+Copilot learns patterns from existing code. This codebase has strong conventions:
 
-## 6. When Not to Use Copilot
+- Dependency injection for testability (see src/tools/)
+- HttpPipeline for all HTTP requests (see src/utils/httpPipeline.ts)
+- Consistent tool structure extending MapboxApiBasedTool
 
-- **Complex Business Logic:** For critical or complex business logic, prefer hand-written code and thorough review.
-- **Legal/Compliance Code:** Do not use Copilot for code with legal, licensing, or compliance implications without explicit review.
+Let Copilot learn these patterns rather than explicitly re-teaching them.
 
 ---
 
-## 7. Continuous Improvement
-
-- **Iterate:** Use Copilot to explore solutions, but always iterate and refine.
-- **Propose Improvements:** Suggest updates to this document as Copilot and our practices evolve.
-
----
+**Remember**: Copilot is an assistant, not an authority. You own the code you commit.

AGENTS.md

@@ -1,27 +1,19 @@
 # AI Agent Instructions for Mapbox MCP Server
 
-## Project Overview
+> **Note**: If you're using Claude Code specifically, see CLAUDE.md instead. This file is for general AI coding assistants.
 
-This is a Model Context Protocol (MCP) server that provides AI agents with access to Mapbox's geospatial services including geocoding, directions, search, and mapping capabilities. The server implements tools for forward/reverse geocoding, route planning, point-of-interest search, static map generation, and geographic data analysis.
+## What This Project Does
 
-## Architecture & Standards
+This is an MCP (Model Context Protocol) server that provides AI applications with geospatial intelligence capabilities through Mapbox APIs. It enables AI agents to understand locations, navigate the physical world, and access spatial data including geocoding, search, routing, travel time analysis, and map visualization.
 
-### Core Technologies
+## Tech Stack
 
-- **Runtime:** Node.js LTS
-- **Language:** TypeScript (strict mode, no JavaScript files)
-- **Testing:** Vitest with comprehensive unit tests
-- **Package Management:** npm
-- **Code Quality:** ESLint + Prettier, pre-commit hooks
+- **Runtime**: Node.js 22+ LTS
+- **Language**: TypeScript (strict mode)
+- **Testing**: Vitest
+- **Package Manager**: npm
 
-### Key Design Patterns
-
-- **Policy Pipeline Architecture:** All HTTP requests use `PolicyPipeline` with configurable policies (UserAgent, Retry, etc.)
-- **Dependency Injection:** Tools accept fetch functions/pipelines via constructor for testability
-- **No Global Pollution:** Avoid patching global objects; use explicit dependency injection
-- **Tool Registration:** Standard MCP tool interface with schema validation
-
-### Project Structure
+## Project Structure
 
 ```
 src/
@@ -31,161 +23,71 @@ src/
 │   ├── MapboxApiBasedTool.ts   # Base class for Mapbox API tools
 │   ├── toolRegistry.ts         # Tool registration system
 │   └── */Tool.ts               # Individual tool implementations
+├── resources/                  # MCP resources (static data)
+│   └── resourceRegistry.ts
 └── utils/
-    ├── fetchRequest.ts         # HTTP policy pipeline system
-    └── versionUtils.ts         # Version info utilities
+    ├── httpPipeline.ts         # HTTP policy pipeline system
+    └── tracing.ts              # OpenTelemetry instrumentation
 
-test/                           # Mirror src/ structure for tests
+test/                           # Mirrors src/ structure
 ```
 
-## Code Quality Guidelines
-
-### TypeScript Standards
-
-- Use strict typing; avoid `any` unless justified with comments
-- All public APIs require JSDoc documentation
-- Follow naming conventions: PascalCase for classes, camelCase for functions/variables
-- Export interfaces and types for external consumption
-
-### Testing Requirements
-
-- **Coverage:** Aim for 100% on critical business logic
-- **Isolation:** Mock external APIs; no real network calls in tests
-- **Structure:** Tests mirror `src/` directory structure
-- **Framework:** Use Vitest exclusively; leverage `vi.fn()` for mocking
-
-### HTTP Request Handling
-
-```typescript
-// Correct: Use PolicyPipeline with dependency injection
-const pipeline = new PolicyPipeline();
-pipeline.usePolicy(new UserAgentPolicy(userAgent));
-pipeline.usePolicy(new RetryPolicy(3, 200, 2000));
-
-class MyTool extends MapboxApiBasedTool {
-  constructor(fetch: typeof fetch = fetchClient) {
-    super({ inputSchema: MySchema });
-    this.fetch = fetch;
-  }
-}
-
-// Incorrect: Global fetch patching
-global.fetch = myCustomFetch; // ❌ Don't do this
-```
-
-### Error Handling
-
-- Handle and log errors gracefully
-- Don't swallow exceptions without proper logging
-- Use appropriate HTTP status codes
-- Provide meaningful error messages to users
+## Critical Patterns
 
-## Development Workflow
+### HTTP Request Architecture
 
-### Pull Request Standards
+- **Never patch global.fetch** - use `HttpPipeline` with dependency injection
+- All HTTP requests flow through the pipeline system (src/utils/httpPipeline.ts:21)
+- Tools receive `httpRequest` via constructor (src/tools/toolRegistry.ts:22-29)
 
-1. **Size:** Keep PRs focused and reasonably sized
-2. **Testing:** Include unit tests for all new functionality
-3. **Documentation:** Update README.md, CHANGELOG.md as needed
-4. **Review:** Require approval from core maintainer
-5. **CI:** All tests and linting must pass
-
-### Commit Standards
-
-- Use conventional commit format
-- Reference GitHub issues where applicable
-- Include breaking change notes in commit body
-
-### Security Guidelines
-
-- **No Secrets:** Never commit API keys, tokens, or credentials
-- **Environment Variables:** Use `.env` files (git-ignored) for local development
-- **Dependencies:** Keep packages updated; monitor for vulnerabilities
-- **Code Review:** Security-sensitive changes require thorough review
-
-## Tool Development Patterns
-
-### Creating New Tools
-
-1. Extend `MapboxApiBasedTool<T>` base class
-2. Define input schema with Zod validation
-3. Implement `execute()` method with proper error handling
-4. Accept fetch function via constructor for testability
-5. Include comprehensive unit tests
-
-### Example Tool Structure
-
-```typescript
-export class ExampleTool extends MapboxApiBasedTool<typeof ExampleSchema> {
-  name = 'example_tool';
-  description = 'Tool description for AI agents';
-
-  constructor(fetch: typeof fetch = fetchClient) {
-    super({ inputSchema: ExampleSchema });
-    this.fetch = fetch;
-  }
-
-  protected async execute(
-    input: z.infer<typeof ExampleSchema>,
-    accessToken: string
-  ): Promise<{ type: 'text'; text: string }> {
-    // Implementation
-  }
-}
-```
+### Tool Development
 
-### Testing Tools
+- Extend `MapboxApiBasedTool` base class (src/tools/MapboxApiBasedTool.ts:16)
+- Accept `httpRequest` parameter in constructor for testability
+- Register in `ALL_TOOLS` array (src/tools/toolRegistry.ts:18)
+- Use `npx plop create-tool` for scaffolding new tools
 
-```typescript
-describe('ExampleTool', () => {
-  beforeEach(() => {
-    vi.stubEnv('MAPBOX_ACCESS_TOKEN', 'test-token');
-  });
+### Testing
 
-  it('handles valid input', async () => {
-    const { fetch, mockFetch } = setupFetch({
-      json: async () => ({ data: 'test' })
-    });
+- Use Vitest exclusively
+- Mock external APIs - no real network calls in tests
+- Use dependency injection to inject mock fetch functions
+- Tests mirror `src/` directory structure
 
-    const tool = new ExampleTool(fetch);
-    const result = await tool.run({
-      /* test input */
-    });
+## Essential Commands
 
-    expect(result.type).toBe('text');
-    expect(mockFetch).toHaveBeenCalledTimes(1);
-  });
-});
+```bash
+npm install              # Install dependencies
+npm test                 # Run tests
+npm run build            # Compile TypeScript
+npm run lint             # Check code quality (auto-fixed by pre-commit hooks)
+npm run inspect:build    # Test with MCP inspector
+npx plop create-tool     # Scaffold a new tool
 ```
 
-## AI Agent Collaboration Notes
+## Common Pitfalls to Avoid
 
-### When Working with This Codebase
+1. **Don't patch globals** - especially `global.fetch`
+2. **Don't make real network calls in tests** - use mocks
+3. **Don't commit without tests** - new features need test coverage
+4. **Don't hardcode secrets** - use environment variables
+5. **Don't ignore type errors** - strict TypeScript is enforced
 
-1. **Read Standards First:** Always consult `CLAUDE.md` for project standards
-2. **Use Existing Patterns:** Follow established patterns in `src/tools/` examples
-3. **Test-Driven Development:** Write tests alongside or before implementation
-4. **Policy Pipeline:** Use `fetchClient` or inject custom fetch for HTTP requests
-5. **Documentation:** Update relevant docs when adding features
+## Documentation
 
-### Common Pitfalls to Avoid
+- **CLAUDE.md** - Detailed standards and patterns for Claude Code users
+- **docs/engineering_standards.md** - Complete engineering guidelines
+- **docs/tracing.md** - OpenTelemetry setup
+- **README.md** - User-facing documentation and integration guides
 
-- Patching global objects (especially `fetch`)
-- Missing unit tests for new functionality
-- Hardcoding configuration values
-- Using JavaScript instead of TypeScript
-- Ignoring ESLint/Prettier warnings
-- Making real network calls in tests
+## Factual Errors to Watch For
 
-### Getting Started
+When analyzing or modifying this codebase:
 
-1. Install dependencies: `npm install`
-2. Run tests: `npm test`
-3. Check linting: `npm run lint`
-4. Format code: `npm run format`
-5. Build project: `npm run build`
-6. Test project: `npm run test`
+- The HTTP pipeline class is `HttpPipeline`, not `PolicyPipeline`
+- The HTTP pipeline file is `src/utils/httpPipeline.ts`, not `fetchRequest.ts`
+- Base tool class uses `httpRequest` parameter, not `fetch`
 
 ---
 
-This codebase prioritizes maintainability, testability, and adherence to MCP standards. When in doubt, refer to existing tool implementations and follow established patterns.
+For detailed code quality standards, testing requirements, and collaboration guidelines, see docs/engineering_standards.md.