Merge pull request #3 from gaarutyunov/claude/issue-1-20260331-0731

gaarutyunov · web-flow · commit 769c56473d5f · 2026-03-31T09:45:32.000+02:00
feat: TASK-01 Repository Scaffold
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,6 @@
+bin/
+*.test
+*.out
+.env
+.env.*
+vendor/
diff --git a/.golangci.yml b/.golangci.yml
@@ -0,0 +1,29 @@
+version: "2"
+linters:
+  enable:
+    - errcheck
+    - gosimple
+    - govet
+    - ineffassign
+    - staticcheck
+    - unused
+    - gofmt
+    - goimports
+    - misspell
+    - revive
+    - exhaustive
+    - noctx
+    - bodyclose
+    - contextcheck
+linters-settings:
+  goimports:
+    local-prefixes: github.com/your-org/mcp-anything
+  revive:
+    rules:
+      - name: exported
+      - name: error-return
+      - name: error-strings
+issues:
+  exclude-use-default: false
+  max-issues-per-linter: 0
+  max-same-issues: 0
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,51 @@
+# CLAUDE.md — AI Agent Instructions for mcp-anything
+
+## Project
+mcp-anything is a stateless Go proxy that converts HTTP REST APIs into MCP (Model Context Protocol) tools.
+Full design: SPEC.md
+
+## Module
+github.com/your-org/mcp-anything
+
+## Commands
+
+### Build
+make build        # go build ./cmd/proxy
+
+### Lint (must pass before every commit)
+make lint         # golangci-lint run ./...
+
+### Vet (must pass before every commit)
+make vet          # go vet ./...
+
+### Unit tests (must pass before every commit)
+make test         # go test -race -count=1 ./...
+
+### Integration tests (require Docker + TC_CLOUD_TOKEN env var)
+make integration  # go test -tags integration -race -count=1 -timeout 300s ./...
+
+### All checks (run before every commit)
+make check        # runs lint + vet + test + build in sequence
+
+## Pre-commit checklist
+Run `make check` and fix all failures before committing. Never commit with failing lint, vet, or unit tests. Integration tests are run in CI but should also pass locally if Docker is available.
+
+## Code conventions
+- All errors must be wrapped with context: `fmt.Errorf("loading spec: %w", err)`
+- No `panic()` in library code; only in `main()` for unrecoverable startup failures
+- Structured logging via `log/slog` with `slog.Default()`; keys are snake_case
+- No global mutable state; pass dependencies explicitly
+- Interfaces are defined in the package that uses them, not the package that implements them
+- Use `context.Context` as the first argument in all functions that do I/O or call other services
+- All config fields that reference secrets use `${ENV_VAR}` syntax; never log expanded values
+- Integration tests live in files named `*_integration_test.go` with build tag `//go:build integration`
+- Unit tests live in files named `*_test.go` with no build tag
+
+## Testcontainers
+Set `TC_CLOUD_TOKEN` environment variable to use Testcontainers Cloud. Without it, tests use the local Docker daemon. The library auto-detects.
+
+## Active development
+This project has no public users. There is no backward compatibility requirement. Interfaces, config schemas, and APIs may change freely between tasks.
+
+## No stubs
+Implementation tasks must produce complete, working code. Do not write placeholder functions that return `nil, nil` or `errors.New("not implemented")`. If a feature is not yet needed, do not create the function at all.
diff --git a/Makefile b/Makefile
@@ -0,0 +1,25 @@
+.PHONY: build lint vet test integration check clean
+
+BINARY := bin/proxy
+GOFLAGS := -race
+INTEGRATION_TIMEOUT := 300s
+
+build:
+	go build -o $(BINARY) ./cmd/proxy
+
+lint:
+	golangci-lint run ./...
+
+vet:
+	go vet ./...
+
+test:
+	go test $(GOFLAGS) -count=1 ./...
+
+integration:
+	go test $(GOFLAGS) -tags integration -count=1 -timeout $(INTEGRATION_TIMEOUT) ./...
+
+check: lint vet test build
+
+clean:
+	rm -rf bin/
diff --git a/README.md b/README.md
@@ -1,2 +1,20 @@
 # mcp-anything
-A configurable gateway that transforms any API into MCP server
+
+A stateless Kubernetes-native proxy that converts any HTTP REST API into an MCP (Model Context Protocol) server. Define your upstream API via an OpenAPI 3.0 spec, optionally apply an OpenAPI Overlay to filter and rename operations, and the proxy automatically generates MCP tools — no code required.
+
+## Status
+Active development. No stability guarantees.
+
+## Design
+See [SPEC.md](SPEC.md) for the full architecture and design decisions.
+
+## Quick start
+(To be filled in when the MVP proxy is working — see TASK-03)
+
+## Development
+Requirements: Go 1.23+, Docker (for integration tests)
+
+    make check        # lint + vet + unit tests + build
+    make integration  # integration tests (requires Docker)
+
+Set `TC_CLOUD_TOKEN` to run integration tests via Testcontainers Cloud.
diff --git a/cmd/proxy/main.go b/cmd/proxy/main.go
@@ -0,0 +1,11 @@
+package main
+
+import (
+	"fmt"
+	"os"
+)
+
+func main() {
+	fmt.Fprintln(os.Stderr, "mcp-anything: not yet implemented")
+	os.Exit(1)
+}
diff --git a/deploy/example/config.yaml b/deploy/example/config.yaml
@@ -0,0 +1,131 @@
+server:
+  port: 8080
+  read_timeout: 30s
+  write_timeout: 60s
+  shutdown_timeout: 10s
+  max_request_body: 1MB
+  startup_validation_timeout: 30s   # per-upstream timeout for jq dry-run at startup
+                                    # on hot-reload: exceeded → abandon reload, keep old config
+  transport:                        # list of enabled transports
+    - streamable-http               # primary: POST+GET on group endpoint paths
+    - sse                           # legacy: GET on {endpoint}/sse paths
+
+telemetry:
+  otlp_endpoint: "otel-collector:4317"
+  service_name: "mcp-anything"
+  service_version: "v0.1.0"
+  insecure: false
+
+# Default inbound auth — applies to all operations unless x-mcp-auth-required: false
+inbound_auth:
+  strategy: jwt   # jwt | introspection | apikey | lua | none
+  jwt:
+    issuer: "https://idp.example.com"
+    audience: "https://mcp.example.com"
+    jwks_url: ""                    # optional; if empty, uses issuer discovery
+  introspection:
+    issuer: "https://idp.example.com"
+    client_id: "${INTROSPECTION_CLIENT_ID}"
+    client_secret: "${INTROSPECTION_CLIENT_SECRET}"
+    audience: "https://mcp.example.com"
+  apikey:
+    header: "X-API-Key"
+    keys_env: "MCP_API_KEYS"        # comma-separated list in env var
+  lua:
+    script_path: "/etc/mcp-anything/auth.lua"
+    timeout: 500ms
+
+naming:
+  separator: "__"
+  max_length: 128
+  conflict_resolution: error        # error | first_wins | skip
+  description_max_length: 1024     # 0 = no truncation
+  description_truncation_suffix: "..."
+  default_slug_rules:
+    replace_slashes: true
+    replace_braces: true
+    lowercase: true
+    collapse_separators: true
+
+upstreams:
+  - name: petstore
+    enabled: true
+    tool_prefix: pets
+    base_url: "https://api.petstore.io/v2"
+    max_response_body: 10MB
+    timeout: 10s
+    tls_skip_verify: false
+    headers:
+      X-Proxy-Source: "mcp-anything"
+
+    openapi:
+      source: "/etc/mcp-anything/specs/petstore.yaml"  # file path or https:// URL
+      auth_header: ""               # "Bearer ${TOKEN}" for private docs
+      refresh_interval: 0           # 0 = no refresh; >0 = background URL refresh
+      max_refresh_failures: 5
+      allow_external_refs: false
+      version: "3.0"
+
+    # Overlay is always applied after spec load and re-applied on every refresh.
+    # source may be a file path or https:// URL.
+    # auth_header and refresh_interval are independent of the spec's values.
+    overlay:
+      source: "/etc/mcp-anything/overlays/petstore-overlay.yaml"
+      auth_header: ""
+      refresh_interval: 0           # 0 = refresh together with openapi.refresh_interval
+
+    outbound_auth:
+      strategy: oauth2_client_credentials
+      oauth2_client_credentials:
+        token_url: "https://idp.example.com/oauth/token"
+        client_id: "${PETSTORE_CLIENT_ID}"
+        client_secret: "${PETSTORE_CLIENT_SECRET}"
+        scopes: ["read:pets", "write:pets"]
+      bearer:
+        token_env: "UPSTREAM_TOKEN"
+      api_key:
+        header: "X-API-Key"
+        value_env: "UPSTREAM_API_KEY"
+        prefix: ""                  # prepended to env value, e.g. "ApiKey "
+      lua:
+        script_path: "/etc/mcp-anything/upstream-auth.lua"
+        timeout: 500ms
+
+    validation:
+      validate_request: true
+      validate_response: true
+      response_validation_failure: warn   # warn | fail
+      success_status: [200, 201, 202, 204]
+      error_status: [400, 401, 403, 404, 422, 429, 500, 502, 503]
+
+  - name: github
+    enabled: true
+    tool_prefix: gh
+    base_url: "https://api.github.com"
+    openapi:
+      source: "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.qkg1.top.yaml"
+      refresh_interval: 1h
+    overlay:
+      source: "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/mcp-overlay.yaml"
+      refresh_interval: 1h
+    outbound_auth:
+      strategy: bearer
+      bearer:
+        token_env: "GITHUB_TOKEN"
+
+groups:
+  - name: all
+    endpoint: /mcp
+    upstreams: [petstore, github]
+    # no filter = all tools from all listed upstreams
+
+  - name: readonly
+    endpoint: /mcp/readonly
+    upstreams: [petstore]
+    # RFC 9535 JSONPath filter evaluated against each operation node
+    filter: "$.paths.*.get[?(@['x-mcp-safe'] == true)]"
+
+  - name: premium
+    endpoint: /mcp/premium
+    upstreams: [petstore, github]
+    filter: "$.paths.*.*[?(@['x-mcp-tier'] == 'premium')]"
diff --git a/deploy/example/overlay-petstore.yaml b/deploy/example/overlay-petstore.yaml
@@ -0,0 +1,32 @@
+overlay: 1.0.0
+info:
+  title: Pet Store MCP Overlay
+  version: 1.0.0
+x-speakeasy-jsonpath: rfc9535
+
+actions:
+  # Remove internal endpoints entirely
+  - target: $.paths['/internal/metrics']
+    remove: true
+
+  # Disable destructive operation — stays in spec but excluded from tools
+  - target: $.paths['/pets/{petId}'].delete
+    update:
+      x-mcp-enabled: false
+
+  # Public health endpoint — no auth required
+  - target: $.paths['/health'].get
+    update:
+      x-mcp-auth-required: false
+
+  # Override tool names and descriptions
+  - target: $.paths['/pets'].get
+    update:
+      x-mcp-tool-name: list_pets
+      description: "List all available pets with optional status filter."
+      x-mcp-safe: true
+
+  # Mark premium operations
+  - target: $.paths['/pets'].post
+    update:
+      x-mcp-tier: premium
diff --git a/deploy/helm/.gitkeep b/deploy/helm/.gitkeep
diff --git a/go.mod b/go.mod
@@ -0,0 +1,32 @@
+module github.com/your-org/mcp-anything
+
+go 1.23
+
+require (
+	github.com/brianvoe/gofakeit/v7 v7.2.1
+	github.com/coreos/go-oidc/v3 v3.17.0
+	github.com/fsnotify/fsnotify v1.9.0
+	github.com/getkin/kin-openapi v0.134.0
+	github.com/go-chi/chi/v5 v5.2.0
+	github.com/itchyny/gojq v0.12.18
+	github.com/knadh/koanf/parsers/yaml v0.1.0
+	github.com/knadh/koanf/providers/file v1.1.2
+	github.com/knadh/koanf/v2 v2.1.2
+	github.com/lucasjones/reggen v0.0.0-20200904144131-37352a28cb6b
+	github.com/modelcontextprotocol/go-sdk v1.3.0
+	github.com/santhosh-tekuri/jsonschema/v6 v6.0.2
+	github.com/speakeasy-api/openapi-overlay v0.10.3
+	github.com/testcontainers/testcontainers-go v0.36.0
+	github.com/yuin/gopher-lua v1.1.1
+	github.com/zitadel/oidc/v3 v3.45.1
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.67.0
+	go.opentelemetry.io/otel v1.35.0
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.35.0
+	go.opentelemetry.io/otel/exporters/prometheus v0.57.0
+	go.opentelemetry.io/otel/metric v1.35.0
+	go.opentelemetry.io/otel/sdk v1.35.0
+	go.opentelemetry.io/otel/sdk/metric v1.35.0
+	go.opentelemetry.io/otel/trace v1.35.0
+	golang.org/x/oauth2 v0.33.0
+	gopkg.in/yaml.v3 v3.0.1
+)
diff --git a/internal/auth/inbound/doc.go b/internal/auth/inbound/doc.go
@@ -0,0 +1,6 @@
+// Package inbound implements pluggable inbound authentication middleware for
+// mcp-anything. Supported strategies are JWT (via go-oidc), token introspection
+// (via zitadel/oidc), API key, and Lua scripting. The middleware validates
+// incoming MCP client credentials and enforces per-operation auth bypass via
+// the x-mcp-auth-required OpenAPI extension.
+package inbound
diff --git a/internal/auth/outbound/doc.go b/internal/auth/outbound/doc.go
@@ -0,0 +1,5 @@
+// Package outbound implements per-upstream outbound authentication providers.
+// Supported strategies are static Bearer token, API key injection, OAuth2
+// client credentials (with automatic token refresh), and Lua scripting.
+// Providers are instantiated at config load time and called per upstream request.
+package outbound
diff --git a/internal/config/doc.go b/internal/config/doc.go
@@ -0,0 +1,4 @@
+// Package config defines all configuration structs for mcp-anything,
+// handles loading from YAML files via koanf, environment variable expansion,
+// and hot-reload watching via fsnotify.
+package config
diff --git a/internal/content/doc.go b/internal/content/doc.go
@@ -0,0 +1,5 @@
+// Package content handles mapping non-JSON upstream responses (images, audio,
+// binary) to the appropriate MCP content types: ImageContent, AudioContent,
+// and ResourceContent. Content-Type detection drives the mapping, with
+// x-mcp-response-format as a per-operation override.
+package content
diff --git a/internal/mcp/doc.go b/internal/mcp/doc.go
@@ -0,0 +1,5 @@
+// Package mcp bootstraps the MCP server using the official go-sdk, registers
+// all generated tools from the upstream registry, and implements the tool call
+// pipeline: prefix-based routing, transform, OpenAPI validation, outbound auth,
+// upstream HTTP dispatch, and response conversion.
+package mcp
diff --git a/internal/openapi/doc.go b/internal/openapi/doc.go
@@ -0,0 +1,5 @@
+// Package openapi handles loading OpenAPI 3.0 specifications from files or URLs,
+// applying OpenAPI Overlays via speakeasy-api/openapi-overlay, auto-generating
+// MCP tool definitions and jq expressions from operations, and validating
+// requests and responses against the spec at runtime.
+package openapi
diff --git a/internal/server/doc.go b/internal/server/doc.go
@@ -0,0 +1,4 @@
+// Package server wires together the net/http server with chi routing, mounts
+// the MCP handler at the configured group endpoints, attaches OTel middleware,
+// and handles graceful shutdown on SIGTERM/SIGINT.
+package server
diff --git a/internal/telemetry/doc.go b/internal/telemetry/doc.go
@@ -0,0 +1,5 @@
+// Package telemetry initialises the OpenTelemetry SDK with OTLP gRPC trace
+// export and Prometheus metric export. It provides HTTP middleware for automatic
+// span and metric emission on both the inbound MCP server and the outbound
+// upstream HTTP clients, following standard HTTP and MCP semantic conventions.
+package telemetry
diff --git a/internal/transform/doc.go b/internal/transform/doc.go
@@ -0,0 +1,5 @@
+// Package transform implements the jq-based request and response transformation
+// engine using gojq. It compiles jq expressions once at config load time and
+// applies them per tool call to construct upstream HTTP requests and transform
+// upstream responses (including error responses) into MCP content.
+package transform
diff --git a/internal/upstream/doc.go b/internal/upstream/doc.go
diff --git a/pkg/crd/doc.go b/pkg/crd/doc.go

-Original file line number
+Diff line change
@@ @@ -0,0 +1,6 @@ @@
 +bin/
 +*.test
 +*.out
 +.env
 +.env.*
 +vendor/