shield

Imported from NoumenaDigital/shield (AGENTS.md). Install upstream with npx skills add NoumenaDigital/shield. Copyright stays with the author.

AI Coding Agent’s Guide for Shield

Shield is the NOUMENA MCP (Model Context Protocol) Gateway. This guide helps AI agents understand the codebase architecture, development workflows, and project-specific patterns.

Essential: Code Style & Testing Requirements

⚠️ ALWAYS apply patterns from .agents/skills/go-idiomatic/SKILL.md when writing or modifying any Go code in this project. This is non-negotiable. Every code change must conform to the idiomatic Go standards documented there, specifically:

• Error handling: Use errors.Is() for comparison, never ==
• Error wrapping: Use fmt.Errorf("%w: %w", ErrType, err) pattern with named error variables
• Cleanup: Use errors.Join() in defer blocks for combining errors
• Control flow: Always prefer switch over else if chains
• Latest Go version: Write code compatible with Go 1.26.1+

Read .agents/skills/go-idiomatic/SKILL.md before making any code changes.

⚠️ ALWAYS apply patterns from .agents/skills/go-testing/SKILL.md when writing tests for this project. This is non-negotiable and strictly enforced by pre-commit hooks. Every test must conform to these standards:

• Test all exported functions
• Use table-driven tests exclusively: map[string]struct{} with t.Run(), never slices
• Compare structs with reflect.DeepEqual() for complete equality checks
• Place compile-time interface checks in source files, not tests
• Use semantic field names: Given / Want in test tables
• Include // Output: sections for Example functions demonstrating usage
• Never use external testing libraries – only standard library

Read .agents/skills/go-testing/SKILL.md before writing any tests.

Project Overview

Shield is a Go implementation of an MCP gateway server. It provides HTTP-based MCP endpoint capabilities using the official modelcontextprotocol/go-sdk. The server runs on port 8081 by default and can be extended with catalog items.

Key Facts:

• Go version: 1.26.1
• Primary dependency: github.com/modelcontextprotocol/go-sdk v1.5.0
• Architecture: Modular design with CLI entry point, configuration, audit logging, policy evaluation, and web UI
• Core flow: cmd/shield/main.go (CLI) → config/ (load config) → internal/server/ (run server) → internal/policy/ (access control) + internal/audit/ (logging)

Architecture & Patterns

Project Structure

cmd/shield/
├── main.go              # CLI entry point, command routing (server / from-catalog subcommands)
internal/
├── audit/               # Structured audit logging for tool calls, resources, prompts
├── catalog/             # Catalog item management and JSON import
├── constants.go         # Package-level constants
├── policy/              # OPA Rego-based policy evaluation for tool access control
├── server/              # MCP server initialization and HTTP handler setup
└── web/                 # Web server for HTML interface / API endpoints
    └── templates/       # Go HTML templates for the HTML interface
config/                  # Configuration types and defaults
docs/
├── AGENTS.md                  # Documentation sync requirements
├── configuration.md           # User-facing configuration reference
├── rego.md                    # User-facing Rego policy authoring guide
└── configuration.schema.json  # JSON Schema for YAML config validation

Development Workflows

Testing

Testing is enforced through pre-commit hooks and follows strict conventions (see go-testing skill):

# Pre-commit hook runs:
go test -short ./...        # Quick unit tests
go fmt ./...                # Code formatting
go vet ./...                # Static analysis
golangci-lint run           # Comprehensive linting (v2.11.4)

Critical Constraints:

• All exported functions must have tests
• Use table-driven tests exclusively (map-based, not slice-based)
• Use reflect.DeepEqual() for struct comparisons
• Place compile-time interface checks in source files, not tests
• Never use external testing libraries

Code Quality Enforcement

Pre-commit hooks enforce quality before commit. See .pre-commit-config.yaml:

• go fmt: Auto-formats all Go files
• go test -short: Runs all tests (must pass before commit)
• go vet: Catches suspicious constructs
• golangci-lint v2.11.4: Comprehensive linting

Go-Specific Conventions

All idiomatic Go patterns are documented in .agents/skills/go-idiomatic/SKILL.md. Key requirements from the Essential: Code Style & Testing Requirements section include:

• ✅ Error handling: Use errors.Is(), never ==
• ✅ Error wrapping: Use fmt.Errorf("%w: %w", ErrType, err) with named error variables
• ✅ Error cleanup: Use errors.Join() in defer blocks
• ✅ Control flow: Prefer switch over else if chains
• ✅ Logging: Use slog.InfoContext() / slog.ErrorContext() with context

Read .agents/skills/go-idiomatic/SKILL.md for detailed patterns and additional conventions (naming, defensive programming, documentation).

Critical Integration Points

MCP SDK Usage

The codebase depends entirely on github.com/modelcontextprotocol/go-sdk:

• mcp.NewServer(): Create MCP server with implementation details
• mcp.NewStreamableHTTPHandler(): Wrap server for HTTP streaming
• mcp.Implementation: Describes server (Name, Version required)

Reference: MCP Specification 2025-11-25

HTTP Server Lifecycle

The server pattern in server.go is the template for all server implementations:

• Creates http.Server with streamable handler
• Listens on TCP with explicit error handling
• Runs in goroutine with channel-based error reporting
• Accepts graceful shutdown via context cancellation

Adding Features

Adding a New Command

Extend the switch statement in cmd/shield/main.go and call a new handler function following the existing pattern (like runServer() or runFromCatalog()).

Adding Policy Control

Tool access control is handled by the policy package using OPA Rego policies. See internal/policy/AGENTS.md for:

• How to load and evaluate policies
• Rego policy file format and conventions
• Testing patterns for policy logic
• Extending the policy system with new entry points

Extending Configuration

Configuration schema and types are in the config package. See config/AGENTS.md for:

• Non-negotiable documentation rules (must update schema and docs)
• Checklist for configuration changes
• Schema and default value management

Web Interface & Templates

The web package provides HTML templates and API endpoints. See internal/web/templates/AGENTS.md for:

• Stylesheet conventions (Noumena Digital Styleguide only)
• Template architecture and rendering pattern
• BEM naming conventions
• Component references

References

• Go: Latest version (1.26.1) – follow current best practices
• MCP Specification: 2025-11-25 version
• OPA Rego: Policy language documentation
• Noumena Styleguide: Design components
• Pre-built Skills: .agents/skills/go-idiomatic/SKILL.md and .agents/skills/go-testing/SKILL.md
• User-facing Docs: docs/configuration.md, docs/rego.md
• Package Guides: See AGENTS.md files in docs/, config/, internal/policy/, and internal/web/templates/

Package-Specific AGENTS.md Files

Certain packages and directories have their own AGENTS.md files with domain-specific guidance:

Always read the package-specific AGENTS.md before making changes to that package. These files contain non-negotiable requirements specific to each domain (e.g., documentation rules for config, styling rules for templates).

Debugging Tips

• Structured logging: Use slog.InfoContext() / slog.ErrorContext() with context - see go-idiomatic skill for logging patterns
• MCP server logs HTTP requests/responses through the handler
• Signal handling: SIGINT/SIGTERM trigger graceful shutdown
• Port conflicts: Default port 8081 must be available
• Context cancellation: Always check ctx.Done() in infinite loops

Tool Usage Guidelines

Terminal Commands (mcp_intellij_execute_terminal_command)

ALWAYS use executeInShell: true when running terminal commands. This ensures:

• Real environment variables are available
• Shell aliases and functions work correctly
• Path resolution matches the user's shell settings
• Pipes, redirects, and shell syntax work as expected

✅ CORRECT:

mcp_intellij_execute_terminal_command({
  command: "go test -short ./...",
  executeInShell: true,
  timeout: 30000
})

❌ WRONG: Never omit executeInShell or set to false

mcp_intellij_execute_terminal_command({
  command: "go test -short ./...",
  timeout: 30000  // Missing executeInShell!
})

Last Updated: April 2026 | Go Version: 1.26.1 | MCP SDK: v1.5.0