googleapis/genai-toolbox

# MCP Toolbox Context & Style Guide

This file (symlinked as `CLAUDE.md`, `AGENTS.md`, and `.gemini/styleguide.md`) provides context and guidelines for AI agents working on the MCP Toolbox for Databases project. It summarizes key information from `CONTRIBUTING.md` and `DEVELOPER.md`.

## Project Overview

**MCP Toolbox for Databases** is a Go-based project designed to provide Model Context Protocol (MCP) tools for various data sources and services. It allows Large Language Models (LLMs) to interact with databases and other tools safely and efficiently.


## Tech Stack

-   **Language:** Go (1.23+)
-   **Documentation:** Hugo (Extended Edition v0.146.0+)
-   **Containerization:** Docker
-   **CI/CD:** GitHub Actions, Google Cloud Build
-   **Linting:** `golangci-lint`

## Key Directories

-   `cmd/`: Application entry points.
-   `internal/sources/`: Implementations of database sources (e.g., Postgres, BigQuery).
-   `internal/tools/`: Implementations of specific tools for each source.
-   `tests/`: Integration tests.
-   `docs/en`: Project documentation. Separated logically into:
    - `documentation/`: Documentation and concepts (Section I).
    - `integrations/`: Reference architectures for DB connectivity and tools (Section II).
    - `samples/`: Tutorials and code samples (Section III).
    - `reference/`: CLI info and FAQs (Section IV).

## Development Workflow

### Prerequisites

-   Go 1.23 or later.
-   Docker (for building container images and running some tests).
-   Access to necessary Google Cloud resources for integration testing (if applicable).

### Building and Running

1.  **Build Binary:** `go build -o toolbox`
2.  **Run Server:** `go run .` (Listens on port 5000 by default)
3.  **Run with Help:** `go run . --help`
4.  **Test Endpoint:** `curl http://127.0.0.1:5000`

### Testing

-   **Unit Tests:** `go test -race -v ./cmd/... ./internal/...`
-   **Integration Tests:**
    -   Run specific source tests: `go test -race -v ./tests/<source_dir>`
    -   Example: `go test -race -v ./tests/alloydbpg`
    -   Add new sources to `.ci/integration.cloudbuild.yaml`
-   **Linting:** `golangci-lint run --fix`


## Developing Documentation

### Prerequisites

-   Hugo (Extended Edition v0.146.0+)
-   Node.js (for `npm ci`)

### Running Local Server

1.  Navigate to `.hugo` directory: `cd .hugo`
2.  Install dependencies: `npm ci`
3.  **Generate Search Index:** Because Pagefind requires physical files, `hugo server` alone will not populate the search bar. Build the local index first (using the development environment to block analytics) by running:
    `hugo --environment development && npx pagefind --site public --output-path static/pagefind`
4.  Start server: `hugo server`

### Versioning Workflows

Documentation builds automatically generate standard HTML alongside AI-friendly text files (`llms.txt` and `llms-full.txt`).

There are 6 workflows in total, handling parallel deployments to both GitHub Pages and Cloudflare Pages. **All deployment workflows automatically execute `npx pagefind --site public` to generate version-scoped search indexes.**

1.  **Deploy In-development docs**: Commits merged to `main` deploy to the `/dev/` path. Automatically defaults to version `Dev`.
2.  **Deploy Versioned Docs**: New GitHub releases deploy to `/<version>/` and the root path. The release tag is automatically injected into the build as the documentation version. *(Note: Developers must manually add the new version to the `[[params.versions]]` dropdown array in `hugo.toml` prior to merging a release PR).*
3.  **Deploy Previous Version Docs**: A manual workflow to rebuild older versions by explicitly passing the target tag via the GitHub Actions UI.

## Coding Conventions

### Tool Naming

-   **Tool Name:** `snake_case` (e.g., `list_collections`, `run_query`).
    -   Do *not* include the product name (e.g., avoid `firestore_list_collections`).
-   **Tool Type:** `kebab-case` (e.g., `firestore-list-collections`).
    -   *Must* include the product name.

### Branching and Commits

-   **Branch Naming:** `feat/`, `fix/`, `docs/`, `chore/` (e.g., `feat/add-gemini-md`).
-   **Commit Messages:** [Conventional Commits](https://www.conventionalcommits.org/) format.
    -   Format: `<type>(<scope>): <description>`
    -   Example: `feat(source/postgres): add new connection option`
    -   Types: `feat`, `fix`, `docs`, `chore`, `test`, `ci`, `refactor`, `revert`, `style`.

 ### PR Title Format

Format: `<type>[optional scope]: <description>`

- **Example:** `feat(source/postgres): add support for "new-field" field`
- **Example (Breaking Change):** `fix(tool/sql)!: change default parameter value`

#### Types

| Type | Description | Version change affected |
| :--- | :--- | :--- |
| **BREAKING CHANGE** | Anything with this type or a `!` after the type/scope introduces a breaking API change. E.g. `fix!: description` or `feat!: description`. | major |
| **feat** | Adding a new feature to the codebase. | minor |
| **fix** | Fixing a bug or typo in the codebase. | patch |
| **ci** | Changes made to the continuous integration configuration files or scripts (usually the yml and other configuration files). | n/a |
| **docs** | Documentations-related PRs, including fixes on docs. | n/a |
| **chore** | Other small tasks or updates that don't fall into any of the types above. | n/a |
| **perf** | changed src code, with improvement of performance metrics. | n/a |
| **refactor** | Change src code but unlike feat, there are no tests broken and no lines lost coverage. | n/a |
| **revert** | Revert changes made in another commit. | n/a |
| **style** | updated src code, with only formatting and whitespace updates. In other words, this includes anything a code formatter or linter changes. | n/a |
| **test** | Changes made to test files. | n/a |
| **build** | Changes related to build of the projects and dependency. | n/a |

#### Scopes

PRs addressing a specific source or tool should **always** add the source or tool name as scope.

The scope is formatted as `<type>/<kind>`. Common scopes include:
- `source/postgres`, `source/cloudsql-mysql`
- `tool/mssql-sql`, `tool/list-tables`
- `auth/google`

**Multiple Scopes:**
- If the PR covers multiple scopes of the same kind, separate them with a comma: `feat(source/postgres,source/alloydbpg): ...`.
- If the PR covers multiple scope types (e.g., adding a new database source and tool), disregard the scope type prefix: `feat(new-db): adding support for new-db source and tool`.

#### PR Description

Every PR must include a description that follows the repository's template:

**1. Description**
A concise description of the changes (bug or feature), its impact, and a summary of the solution.

**2. PR Checklist**
- [ ] Make sure to open an issue as a bug/issue before writing your code!
- [ ] Ensure the tests and linter pass
- [ ] Code coverage does not decrease (if any source code was changed)
- [ ] Appropriate docs were updated (if necessary)
- [ ] Make sure to add `!` if this involves a breaking change

**3. Issue Reference**
Use the format: `Fixes #<issue_number> 🦕`

## Adding New Features

### Adding a New Data Source

1.  Create a new directory: `internal/sources/<newdb>`.
2.  Define `Config` and `Source` structs in `internal/sources/<newdb>/<newdb>.go`.
3.  Implement `SourceConfig` interface (`SourceConfigType`, `Initialize`).
4.  Implement `Source` interface (`SourceType`).
5.  Implement `init()` to register the source.
6.  Add unit tests in `internal/sources/<newdb>/<newdb>_test.go`.

### Adding a New Tool

1.  Create a new directory: `internal/tools/<newdb>/<toolname>`.
2.  Define `Config` and `Tool` structs.
3.  Implement `ToolConfig` interface (`ToolConfigType`, `Initialize`).
4.  Implement `Tool` interface (`Invoke`, `ParseParams`, `Manifest`, `McpManifest`, `Authorized`).
5.  Implement `init()` to register the tool.
6.  Add unit tests.

### Adding Documentation

-   **For a new source:** Add source documentation to `docs/en/integrations/<source_name>/source.md`. Ensure the root `_index.md` file contains **strictly only frontmatter** and no markdown body text.
-   **For a new native tool:** Add tool documentation to `docs/en/integrations/<source_name>/tools/<tool_name>.md`. Ensure the `tools/_index.md` file contains **strictly only frontmatter**.
-   **Adding Integration Samples:** Add integration-specific samples to `docs/en/integrations/<source_name>/samples/`. Ensure the `samples/_index.md` file contains **strictly only frontmatter**.
-   **Tool Inheritance (Shared Tools):** Managed databases (e.g., Cloud SQL Postgres) that use the tools of their underlying engine (e.g., Postgres) map their inherited tools by utilizing the `shared_tools` frontmatter parameter inside their `tools/_index.md` file. This file must contain only frontmatter.
-   **New Top-Level Directories:** If adding a completely new top-level section to the documentation site, you must update the "Diátaxis Narrative Framework" section inside both `.hugo/layouts/index.llms.txt` and `.hugo/layouts/index.llms-full.txt` to keep the AI context synced with the site structure.


#### Integration Documentation Rules

When generating or editing documentation for this repository, you must strictly adhere to the following CI-enforced rules. Failure to do so will break the build.

##### Source Page Constraints (`integrations/**/source.md`)

1.  **File Naming:** The primary connection guide for a source must be named `source.md`. Use `_index.md` solely as an empty structural folder wrapper containing **only YAML frontmatter**.
2.  **LinkTitle:** The linkTitle has to be set to the string `Source` always.
3.  **Title Convention:** The YAML frontmatter `title` must always end with "Source" (e.g., `title: "Postgres Source"`).
4.  **No H1 Tags:** Never generate H1 (`#`) headings in the markdown body.
5.  **Strict H2 Ordering:** You must use the following H2 (`##`) headings in this exact sequence.
    *   `## About` (Required)
    *   `## Available Tools` (Optional)
    *   `## Requirements` (Optional)
    *   `## Example` (Required)
    *   `## Reference` (Required)
    *   `## Advanced Usage` (Optional)
    *   `## Troubleshooting` (Optional)
    *   `## Additional Resources` (Optional)
6.  **Shortcode Placement:** If you generate the `## Available Tools` section, you must include the `{{< list-tools >}}` shortcode beneath it.

##### Tool Page Constraints (`integrations/**/tools/*.md`)

1.  **Location:** All native tools must reside inside a nested `tools/` subdirectory. The `tools/` directory must contain an `_index.md` file consisting **strictly of frontmatter**.
2.  **No H1 Tags:** Never generate H1 (`#`) headings in the markdown body.
3.  **Strict H2 Ordering:** You must use the following H2 (`##`) headings in this exact sequence.
    *   `## About` (Required)
    *   `## Compatible Sources` (Optional)
    *   `## Requirements` (Optional)
    *   `## Parameters` (Optional)
    *   `## Example` (Required)
    *   `## Output Format` (Optional)
    *   `## Reference` (Optional)
    *   `## Advanced Usage` (Optional)
    *   `## Troubleshooting` (Optional)
    *   `## Additional Resources` (Optional)
4.  **Shortcode Placement:** If you generate the `## Compatible Sources` section, you must include the `{{< compatible-sources >}}` shortcode beneath it.

##### Samples Architecture Constraints
Sample code is aggregated visually in the UI via the Samples section, but the physical markdown files are distributed logically based on their scope.
1.  **Quickstarts:** `docs/en/documentation/getting-started/`
2.  **Integration-Specific Samples:** `docs/en/integrations/<source_name>/samples/`. (The `samples/_index.md` wrapper must contain **strictly only frontmatter**).
3.  **General/Cross-Category Samples:** `docs/en/samples/`

##### Samples Maintenance Rules

1. **Filtering:** Always include `sample_filters` in the frontmatter. Use specific tags for:
   * Data Source (e.g., `bigquery`, `alloydb`)
   * Language (e.g., `python`, `js`, `go`)
   * Tool Type (e.g., `mcp`, `sdk`)
2. **Metadata:** Ensure `is_sample: true` is present to prevent the sample from being excluded from the Samples Gallery.

##### Prebuilt Config Constraints (`integrations/**/prebuilt-configs/*.md`)

1. **Naming & Path:** All prebuilt config docs must reside in `prebuilt-configs/`.
2. **Shortcode Requirement:** The main `documentation/configuration/prebuilt-configs/_index.md` page uses the `{{< list-prebuilt-configs >}}` shortcode, which only detects directories named exactly `prebuilt-configs`.
3. **YAML Mapping:** Always verify the `kind` of the data source in `internal/prebuiltconfigs/tools/` before choosing the integration folder.


##### Asset Constraints (`docs/`)

1.  **File Size Limits:** Never add files larger than 24MB to the `docs/` directory.