mirror of
https://github.com/xlionjuan/searxng-mcp-go.git
synced 2026-11-16 19:40:03 +00:00
6.9 KiB
6.9 KiB
SearXNG MCP Server
A Model Context Protocol (MCP) server providing web search via the SearXNG meta-search engine. Agents call this server to perform web searches through a configured SearXNG instance.
Orientation
- Entry points:
main.go,cli.go,mcp.go,format.go - Core package:
internal/searxng/ - Answer types and deduplication:
internal/searxng/answer/ - Shared test helpers:
internal/testhelper/ - Unit and integration tests: root
*_test.goplusinternal/searxng/*_test.go - E2E and stress tests:
e2e_*_test.go, build tagse2eandstress - Golden regression test:
golden_capture_test.gois a byte-for-byte lock onformatResults()output. Any intentional formatting change requires updating the inline golden string in that test. - Fixtures:
testdata/ - CI and release workflows:
.github/workflows/ - GitHub Actions OpenCode runtime:
docs/agents/opencode-github-actions.md - Domain context and terminology:
CONTEXT.md - Architecture decisions:
docs/adr/
Documentation Index
| Topic | Document |
|---|---|
| Local SearXNG test server | docs/agents/test-server.md |
| Pull-request agent workflow | docs/agents/pull-requests.md |
| Code review workflow | docs/agents/code-review.md |
| GitHub Actions OpenCode runtime | docs/agents/opencode-github-actions.md |
| Release agent workflow | docs/agents/release.md |
| Issue tracker workflow | docs/agents/issue-tracker.md |
| Domain and ADR workflow | docs/agents/domain.md |
| Architecture decisions | docs/adr/ |
Code Cleanliness
- Remove junk files (
.bak,.test,*~,.swp,.swo) before committing. .gitignorealready covers*.bak,*.test,*.swp,*.swo,*.out,REPORT.md,.env;*~is not.
Local Review Reports
REPORT.mdis local-only scratch (.gitignored). See docs/agents/local-reports.md.
Project Rules
Do Not Change
- Do not modify
.gitignoreunless explicitly asked. - Do not change the MCP handler's User-Agent header.
CI and Release
- Run the release workflow only when the user explicitly asks for a release and the target version is known or confirmed. See docs/agents/release.md.
- CI workflow rules: docs/agents/ci.md.
- In GitHub Actions OpenCode, any dirty worktree may be committed and pushed by the action infrastructure. For read-only requests, do not leave local changes; see docs/agents/opencode-github-actions.md.
E2E Tests
- Core functional E2E tests assert non-zero results, with a WARNING SUMMARY path for live-server edge cases.
- Owner-approved exceptions must not be broadened without approval. See docs/agents/e2e-tests.md.
- For local server setup, use
just test-server-start; never runsearxng-server-test/01-start-fg.shfrom agents or CI. See docs/agents/test-server.md.
Documentation
- All docs (
docs/*.md, README, CONTEXT, AGENTS) must be in English. - Pull requests must update related documentation; see docs/agents/pull-requests.md.
Editing
- Use patch-style edits for existing files; avoid
sed -iand ad hoc rewrites. - For new files, use an available file-edit/write primitive rather than shell heredocs or command-output redirection.
Go Skill Corpus
- When the optional
cc-skills-golangcorpus is available, every AI agent working on Go code must locate and read the relevant skill files before editing, reviewing, or claiming completion. - For coding tasks, first identify the implementation domains involved, such as error handling, concurrency, context propagation, CLI behavior, testing, security, dependencies, or performance. Then read the matching
cc-skills-golangskill files. Do not limit coding work to the review-focused skill subset. - For code review tasks, follow docs/agents/code-review.md and read the review-relevant skills named there before producing findings.
- Repository rules and local project context override generic skill advice.
Go Toolchain
Never manually install Go. Run which go before any Go command. If which go fails, report and stop — do not install, download, or work around it.
Verification
- Before every commit that touches Go code, tests, dependencies, or Go-related scripts/workflows, the committing agent must run
just verifylocally. This is the canonical verification gate defined in docs/agents/verification.md. Do not guess or compose a custom verification command — usejust verify. just verifycovers build, vet, lint, test (with race detector), stress tests, mod tidy, and coverage. It mirrors the non-E2E CI pipeline.- Pure documentation changes (
.mdfiles only) do not requirejust verify.
GitHub and PR Work
- Use
ghCLI for all GitHub operations (not browser tools). - For code review requests, follow docs/agents/code-review.md.
- PR title and body must be in English and follow the repository PR title policy whenever an agent creates or updates PR metadata. See docs/agents/pull-requests.md for the full PR workflow, title policy, and body checklist.
- PR agents must create requested PRs with
gh pr create; do not stop after pushing a branch. For OpenCode running inside GitHub Actions, see docs/agents/opencode-github-actions.md.
Git Configuration
- Treat all Git configuration as read-only. Agents may inspect Git config, but must not write, unset, or override any Git config at repo, worktree, global, system, file, submodule, or per-command (
git -c) scope unless the current human explicitly names the config key to change. If Git fails because config or identity is missing, unsafe, or wrong, stop and report; do not repair, guess, or work around it.
Git Identity
- Use the existing git identity as-is. Inspect with
git config --get user.name/git config --get user.email. Do not set, override, or hard-code author/committer identity. - A commit with known wrong author metadata is tainted: do not make it the tip of any branch. See docs/agents/pull-requests.md#git-identity.
Agent Workflows
- Issues: docs/agents/issue-tracker.md
- Pull requests: docs/agents/pull-requests.md
- Code review: docs/agents/code-review.md
- GitHub Actions OpenCode runtime: docs/agents/opencode-github-actions.md
- Release: docs/agents/release.md
- Domain and ADR: docs/agents/domain.md