mcp-wireshark: Instructions file for Claude Code

CLAUDE.md — mcp-wireshark

Project instructions for Claude Code. Read this before making any changes.

Purpose

This is an MCP server that gives AI assistants (Claude, Copilot, etc.) direct access to Wireshark/tshark. The primary audience is IEC 61850 engineers who need to analyze substation network traffic (GOOSE, MMS, Sampled Values) and the broader network/security community. Every design decision should serve two goals:

1. Token efficiency — MCP tool responses are fed directly into an LLM context window. Bloated output burns tokens and degrades reasoning quality.
2. Correctness and safety — tshark is run as a subprocess with user-supplied arguments. Input validation is critical.

---

Architecture

src/mcp_wireshark/
  server.py        — Server instance + list_tools()/call_tool() routing only
  read_tools.py    — Read-only tools: schemas, handlers, READ_TOOLS, READ_HANDLERS
  write_tools.py   — Write tools (capture/export): schemas, handlers, WRITE_TOOLS, WRITE_HANDLERS
  validation.py    — validate_file_path(), validate_display_filter(), security constants
  utils.py         — run_tshark(), run_dumpcap(), parse_packet_json(), WiresharkNotFoundError
  types.py         — TypedDicts: PacketInfo, InterfaceInfo, ProtocolStats, TCPStream
  cli.py           — Entry point: asyncio.run(server.main())
  __init__.py      — Public API + __version__
tests/
  test_server.py   — Validation logic + handler integration tests
  test_utils.py    — run_tshark mocking
  conftest.py      — Shared fixtures

Read vs Write — every new tool declares which:

• Read tools have no side effects (list interfaces, pcap analysis, version checks). They live in read_tools.py with readOnlyHint=True.
• Write tools capture traffic, write files, or change state. They live in write_tools.py with readOnlyHint=False, destructiveHint=False (additive — they create new files but don't delete user data).

Adding a tool is always 4 steps:

1. Decide read vs write.
2. Append a Tool(...) entry (with ToolAnnotations(...)) to READ_TOOLS or WRITE_TOOLS.
3. Write async def handle_tool_name(arguments: dict[str, Any]) -> list[TextContent] in the same module and register it in READ_HANDLERS / WRITE_HANDLERS.
4. Add tests in tests/test_server.py.