# Adding New Tools to TomTom Maps MCP

This guide explains how to add a new **tool** (API integration) to the TomTom Maps MCP repository. It covers structure, coding, testing, and documentation best practices.

---

## 1️⃣ Preparation

Before starting, collect all relevant information about the API you want to integrate:

* **Base URL** and available **endpoints**.
* Authentication requirements (API key, OAuth, etc.).
* Supported HTTP methods and query/path parameters.
* Expected request/response payloads.
* Rate limits, quotas, and timeouts.
* Error format and retry recommendations.

> Keep this info handy; it will guide service implementation and schema design.

---

## 2️⃣ Create the Service Layer

The service is responsible for talking to the external API.

1. Inside `src/services/`, create a folder for your service, e.g. `elevation/`.
2. Add three files:

   * `service.ts`: the implementation (HTTP calls, error handling, parsing).
   * `types.ts`: TypeScript interfaces for request/response.
   * `service.test.ts`: unit/integration tests for the service.

**Example structure:**

```
src/services/elevation/
├── service.ts
├── service.test.ts
└── types.ts
```

### Tips

* Keep `service.ts` focused on API logic only.
* Export clear, typed functions (e.g., `getElevation(params: ElevationRequest): Promise<ElevationResponse>`).
* Use environment variables for secrets (update `.env.example`).
* Add retries or caching if the API is rate-limited.

---

## 3️⃣ Define Schemas

Schemas validate inputs (and optionally outputs) for the tool.

1. Create a schema file under `src/schemas/`, e.g. `elevationSchema.ts`.
2. Export a JSON Schema or TypeScript type describing allowed parameters.

> This ensures invalid input is caught before calling the API.

---

## 4️⃣ Implement the Tool

Tools live in `src/tools/` and define how MCP exposes the service.

1. Create a file (e.g. `elevationTool.ts`).
2. Export an object with:

   * `name`: unique identifier (e.g., `tomtom-elevation`).
   * `description`: short explanation.
   * `inputSchema`: schema from step 3.
   * `handler`: async function calling the service and returning formatted output.

---

## 5️⃣ Register the Tool

Update the server bootstrap (`src/createServer.ts` or equivalent):

```ts
import { elevationTool } from './tools/elevationTool';

const tools = [
  ...existingTools,
  elevationTool
];
```

This makes the tool available through the MCP protocol.

---

## 6️⃣ Write Tests

* **Service tests** (`service.test.ts`): Cover success, error, and edge cases.
* **Tool tests** (optional but recommended): Validate that MCP input/output works correctly.
* Use mocks for network calls where feasible.

> Run tests locally and in CI to ensure stability.

---

## 7️⃣ Documentation

* Update or create entries in `docs/` describing the new tool:

  * Purpose and endpoints used.
  * Example requests/outputs.
  * Special requirements (auth, rate limits, etc.).
* Mention the tool in the "Available Tools" section of the main README if appropriate.

---

## 8️⃣ Review & Deploy

* Verify naming consistency (tool, files, schemas).
* Check linting and formatting.
* Ensure environment variables are documented.
* Run all tests and integration checks before merging.

---

### ✅ Summary Checklist

* [ ] Gather API details and authentication.
* [ ] Create `service.ts`, `types.ts`, and `service.test.ts`.
* [ ] Define an input schema.
* [ ] Implement a tool with `name`, `description`, `inputSchema`, and `handler`.
* [ ] Register the tool in `createServer.ts`.
* [ ] Add unit/integration tests.
* [ ] Document the tool in `docs/` and README.
* [ ] Verify environment variables and rate limits.

---

Following these steps keeps the repository modular, type-safe, and easy to maintain while extending its capabilities with new APIs.