Skip to content

Architecture Decision Records - Katana MCP Server

This directory contains Architecture Decision Records (ADRs) specific to the katana-mcp-server package.

What is an ADR?

An Architecture Decision Record (ADR) is a document that captures an important architectural decision made along with its context and consequences.

Format

We use the format proposed by Michael Nygard in his article Documenting Architecture Decisions:

  • Title: A short noun phrase describing the decision
  • Status: Proposed | Accepted | Deprecated | Superseded
  • Context: What is the issue that we're seeing that is motivating this decision?
  • Decision: What is the change that we're proposing and/or doing?
  • Consequences: What becomes easier or more difficult to do because of this change?

ADR Lifecycle

  1. Proposed: The ADR is proposed and under discussion
  2. Accepted: The ADR has been accepted and is being implemented
  3. Deprecated: The ADR is no longer recommended but still in use
  4. Superseded: The ADR has been replaced by another ADR

Index

Accepted Architecture Decisions

Proposed Architecture Decisions

Creating a New ADR

  1. Copy the template from the shared ADR directory:
cp docs/adr/template.md katana_mcp_server/docs/adr/NNNN-your-title.md

  1. Use the next number across all three ADR directories — the sequence is shared between katana_public_api_client/docs/adr/ (client package), docs/adr/ (monorepo-level), and this directory (MCP-server-specific), not per-package. Check the highest existing number across all three.

  2. Decide which directory the ADR belongs in: client package decision → katana_public_api_client/docs/adr/; monorepo / build / process → docs/adr/; MCP-server-specific architecture → here.

  3. Fill in the sections

  4. Create a PR for discussion

  5. After acceptance, update status to "Accepted"