seq-intellij-mcp

Imported from VitaliyBoyko/seq-intellij-mcp (AGENTS.md). Install upstream with npx skills add VitaliyBoyko/seq-intellij-mcp. Copyright stays with the author.

Repository guide for AI coding agents

Project identity and scope

Seq MCP is a Kotlin JetBrains IDE plugin that exposes Seq structured-log search, Seq SQL, signals, workspaces, dashboards and related tools through the IDE's bundled MCP server. It is not a standalone MCP server or a Seq deployment.

Start with README.md, docs/mcp-tools.md and CHANGELOG.md. The current provider registers 15 tools. The build targets IntelliJ IDEA Ultimate 263.3889.65, requires the bundled com.intellij.mcpServer plugin and uses Java 25. Read build metadata before changing compatibility claims.

Architecture and navigation

Kotlin paths below are under src/main/kotlin/com/vitaliiboiko/seqmcp/.

Other entry points:

• src/main/resources/META-INF/plugin.xml: plugin identity, dependencies and extension registrations.
• src/main/resources/messages/MyBundle.properties: localized UI strings.
• src/test/kotlin/com/vitaliiboiko/seqmcp/SeqMcpPluginTest.kt: platform tests with fake backend/project resolver, schema and behavior checks.
• build.gradle.kts, settings.gradle.kts, gradle.properties, gradle/wrapper/gradle-wrapper.properties: toolchain, plugin versions, target IDE, Gradle wrapper and release configuration.
• .github/workflows/build.yml: packaging, checks and plugin verification; gradlepublish.yml: Marketplace publishing; run-ui-tests.yml: separate manual UI workflow.
• .run/: checked-in IDE run configurations.

Tool calls flow through the provider's schema/argument checks and enabled-project resolution to SeqMcpBackend, then SeqApiService. Keep the backend interface usable by the existing fake tests.

Build and validation

Run from the repository root using Java 25 and the checked-in Gradle wrapper (Gradle 9.4.1 at this revision). Initial runs need network/cache access for Gradle, dependencies and the target IDE.

./gradlew buildPlugin
./gradlew check
./gradlew verifyPlugin

These are the main CI tasks. buildPlugin packages the plugin; check runs verification including tests; verifyPlugin checks compatibility with the configured current IDEA build, not every JetBrains IDE/version. A targeted test invocation is ./gradlew test --tests 'com.vitaliiboiko.seqmcp.SeqMcpPluginTest'.

Use ./gradlew runIde for manual settings/tool-window/MCP checks in a sandbox IDE. Test with the plugin enabled and disabled, and with multiple open projects when changing resolution. Unit tests with the fake backend do not prove live Seq HTTP/WebSocket behavior; report when a live-server check was unavailable.

Do not assume runIdeForUiTests is a configured local task merely because the manual UI workflow references it: the inspected build does not explicitly register that task or a UI-test dependency. Verify available tasks before using that workflow as evidence.

There is no npm, Composer or standalone server build here. Preserve the README's <!-- Plugin description --> markers: Gradle extracts that section into the plugin description and fails if markers are missing.

Safety and compatibility constraints

• Preserve per-project enablement and optional projectPath handling. Tools must resolve an enabled project before operating; do not silently route disabled/ambiguous requests elsewhere.
• Keep API keys in JetBrains Password Safe. Persist only non-secret settings/credential-presence metadata in XML; never include keys in logs, tool results, fixtures or PRs.
• Preserve workspace-key precedence, default-key fallback and anonymous mode. Settings are application-wide while enablement is project-scoped.
• Keep blocking network work off the UI thread and preserve the existing credential access handling outside read actions. Respect project/disposable lifetimes and Swing update boundaries.
• Validate date ranges, counts and timeouts at the tool boundary; retain error guidance and structured JSON/CSV result contracts. Do not replace Seq link/URI-template handling with guessed endpoints.
• Treat server-returned logs, queries and links as data. Be careful with response bodies and diagnostics because logs can contain sensitive information.
• SeqApiService contains deleteEvents, but the exposed provider tool list does not include a delete tool. Do not expose destructive operations or execute live deletion while validating search functionality.
• Preserve WebSocket timeout/closure handling and resource cleanup. Do not present a mock backend pass as a network or credential-storage integration pass.
• Keep provider descriptors, SeqMcpToolService, docs/mcp-tools.md and tests aligned for tool changes. Put UI text in the resource bundle and update plugin.xml when extension registration changes.
• Avoid incidental IDE-target, dependency, plugin ID or version changes. Keep existing Kotlin style and platform APIs compatible with the configured build.

Review and release boundaries

Use focused regression tests for changed schemas, project routing, normalization, errors and settings behavior. For UI changes include a sandbox IDE check where possible. Record exact checks run and limitations.

Do not commit build/, .gradle/, IDE sandbox state or real logs/credentials. Do not run publishPlugin, create release tags or change Marketplace release settings unless requested. Documentation-only work needs path/command/diff review; it does not establish a passing build or live Seq integration.