# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Status

**This repository is freshly initialized.** The only Go source file is `main.go`, which is still the GoLand "Hello, gopher" template. The `go.mod` and `go.sum` already pin the intended runtime dependencies, but no application code has been written yet.

Intended purpose (inferred from module name and pinned dependencies): an **MCP (Model Context Protocol) server for Apache Spark**, written in Go, with HTTP transport, MongoDB-backed persistence, and a local `data/` directory for Spark connection state and pending job state (per `.gitignore`).

When working here, expect to be **building from scratch**, not modifying existing logic.

## Build, Test, Run

Standard Go toolchain (Go 1.25.5 per `go.mod`). All commands run from the repo root.

| Task | Command |
|---|---|
| Build | `go build ./...` |
| Run | `go run .` (currently just prints the template `main`) |
| Test (all) | `go test ./...` |
| Test (single test by name regex) | `go test -run TestName ./...` |
| Test (single test verbose) | `go test -v -run TestName ./path/to/pkg` |
| Test (with coverage) | `go test -cover ./...` |
| Vet (static analysis) | `go vet ./...` |
| Format | `gofmt -w .` |
| Tidy modules | `go mod tidy` |
| Download deps | `go mod download` |

There is no `Makefile`, no `golangci-lint` config, and no test files yet — do not assume they exist.

## Key Pinned Dependencies

`go.mod` declares these as `// indirect` (they will become direct once code is added that imports them):

- **`github.com/mark3labs/mcp-go v0.56.0`** — MCP server framework. This is the core library; all MCP tool/resource/prompt definitions will be built on top of it.
- **`github.com/gin-gonic/gin v1.12.0`** — HTTP router. Likely the transport layer that exposes the MCP server over HTTP (SSE / streamable HTTP).
- **`go.mongodb.org/mongo-driver/v2 v2.5.0`** — MongoDB client. Likely for persisting connection profiles, session state, and job history.
- **`github.com/bytedance/sonic v1.15.0`** — High-performance JSON encoder used internally by Gin.

## Layout Conventions

- Module path: `spark-mcp-go` (see `go.mod:1`). Local package import paths use this prefix.
- Runtime data directory: `data/` at the repo root, **gitignored**. Used for "persisted Spark connections / pending jobs" (per `.gitignore` comment). Anything that needs to survive across process restarts but should not go to MongoDB belongs here.
- IDE config: `.idea/` is gitignored — JetBrains (GoLand / IntelliJ) workspace files. Safe to delete; not part of the project.

## Things To Confirm Before Coding

The codebase is empty enough that a few decisions are not yet pinned down and will affect every subsequent file. Confirm with the user before assuming:

1. **MCP transport** — stdio, HTTP+SSE, or streamable HTTP? The Gin dependency suggests HTTP, but `mark3labs/mcp-go` supports both.
2. **Spark connectivity** — does this server submit jobs to an existing Spark cluster (REST / Livy / Spark Connect), or does it embed a Spark session (likely not — Spark itself is JVM/Scala and won't run in a Go binary)?
3. **Persistence split** — what goes in MongoDB vs. the local `data/` directory? The `.gitignore` implies both will be used.
4. **Configuration** — env vars? config file (YAML/JSON)? CLI flags? Nothing is wired up yet.

## Memory

This is a fresh repo with no `MEMORY.md` or project-level memory file. Decisions made during early development (transport choice, Spark backend interface, persistence schema) are worth recording once they are made — see the `claude-md-management` skill conventions.