You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .agents/skills/validate-search-filters/SKILL.md
+46-44Lines changed: 46 additions & 44 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,6 +5,8 @@ license: MIT
5
5
compatibility: Requires kubectl configured against the LFX v2 Kubernetes cluster (dev or prod). The OpenSearch cluster is an AWS-managed OpenSearch Service domain reachable only from within the cluster network — queries are tunnelled through the NATS box pod using kubectl exec.
6
6
---
7
7
8
+
# Validate Search Filters
9
+
8
10
Validate every filter parameter across all tools that use the query service SDK
9
11
in `internal/tools/` against the live OpenSearch `resources` index and the
10
12
upstream indexer-contract documentation. Produce a per-filter verdict table
This is the **LFX MCP Server** — a Model Context Protocol (MCP) implementation in Go that exposes the Linux Foundation's LFX platform as MCP tools for AI agents. It uses the official MCP Go SDK and supports JSON-RPC 2.0 over stdio (dev) and Streamable HTTP (production) transports.
6
+
7
+
**Key facts**: ~25 Go source files, single binary, no database, stateless HTTP mode. Go and MCP SDK versions are pinned in `go.mod`. Built with `ko` for container images. Deployed to Kubernetes via Helm.
8
+
9
+
---
10
+
11
+
## CI Rules (what breaks the build)
12
+
13
+
Two workflows run on every PR (`.github/workflows/`):
14
+
15
+
1.**`license-header-check.yml`** — tracked source/config files (Go, YAML, shell, Makefile, etc.) must begin with the license header.
16
+
2.**`mega-linter.yml`** — MegaLinter Go flavor v9 (config: `.mega-linter.yml`).
17
+
18
+
### Requirements for new/modified files
19
+
20
+
**License header** — always include as the first lines:
21
+
22
+
```go
23
+
// Copyright The Linux Foundation and contributors.
24
+
// SPDX-License-Identifier: MIT
25
+
```
26
+
27
+
For YAML, shell, and Makefile use `#` comment syntax. Missing headers are the #1 cause of CI failure.
28
+
29
+
**Package doc comment** — every non-test `.go` file must have `// Package <name> ...` immediately above the `package` declaration. The `GO_REVIVE` linter enforces the `package-comments` rule. `_test.go` files are exempt.
30
+
31
+
**YAML formatting** — keep lines ≤120 characters (config: `.yamllint`); this is a warning, not a build failure. Helm templates in `charts/lfx-mcp/templates/` are excluded from YAML linting.
32
+
33
+
**Other MegaLinter checks:** the Go flavor bundles a full set of Go and common scripting/CI linters (shell, Docker, GitHub Actions, Helm, Markdown, secrets, etc.) and runs them all by default. `.mega-linter.yml` is the single source of truth for what's disabled or downgraded to error-only — check it rather than relying on any list here.
34
+
35
+
---
36
+
37
+
## Project Layout
38
+
39
+
```text
40
+
cmd/lfx-mcp-server/main.go — Entry point, config, flag parsing, tool registration
41
+
internal/tools/ — All MCP tool implementations (one file per tool/domain)
.yamllint — YAML lint rules (max line length: 120)
52
+
.ko.yaml — ko builder config with ldflags
53
+
Dockerfile — Multi-stage build (Chainguard base images)
54
+
AGENTS.md — Detailed developer guide (canonical; CLAUDE.md is a symlink)
55
+
ARCHITECTURE.md — System architecture with Mermaid diagrams
56
+
```
57
+
58
+
---
59
+
60
+
## Adding or Modifying Tools
61
+
62
+
Each tool lives in `internal/tools/<domain>.go`. The pattern is:
63
+
64
+
1. Define an args struct with `json` + `jsonschema` tags.
65
+
2. Write a `Register<ToolName>(server *mcp.Server)` function that calls `mcp.AddTool`.
66
+
3. Write a `handle<ToolName>` function implementing the logic.
67
+
4. Register the tool in `cmd/lfx-mcp-server/main.go` inside `newServer()`, gated on `canRead` or `canManage`.
68
+
5. Add the tool name to the `defaultTools` slice (also in `main.go`) if it should be enabled by default.
69
+
70
+
Tool annotations: always set `ReadOnlyHint: true` for read tools. Write tools must explicitly set `DestructiveHint`.
71
+
72
+
---
73
+
74
+
## Key Conventions
75
+
76
+
-**Package comments**: Every non-test `.go` file needs a `// Package <name> ...` comment (revive enforces this; `_test.go` files are exempt).
77
+
-**Error constant**: Use `const errKey = "error"` for structured logging error keys.
78
+
-**Logging**: Use `slog` (Go stdlib). Debug-only logs use `slog.Debug(...)`.
79
+
-**No wrapper functions for scope enforcement** — tool gating is done inline in `newServer()`.
80
+
-**JSON schema generation**: The MCP SDK auto-generates schemas from struct tags; no manual schema files.
81
+
-**`schemaCache`**: A package-level cache shared across per-request server instances; do not duplicate it.
82
+
83
+
---
84
+
85
+
## Common Pitfalls
86
+
87
+
- Forgetting the license header on new files is the #1 cause of CI failure.
88
+
- New non-test `.go` files without a package doc comment will fail the revive `package-comments` rule.
89
+
- The `defaultTools` list in `main.go` controls which tools are enabled by default; adding a Register call without adding the name to `defaultTools` means the tool won't run unless explicitly enabled via `-tools`/`LFXMCP_TOOLS`.
90
+
- Helm chart templates (`charts/lfx-mcp/templates/`) are excluded from YAML linting via regex in `.mega-linter.yml`.
91
+
92
+
---
93
+
94
+
## Trust These Instructions
95
+
96
+
These instructions are validated and current. Only perform additional exploration if the information above is incomplete or produces errors. For detailed architecture, tool patterns, and environment variable reference, consult `AGENTS.md` in the repo root.
0 commit comments