v1.7.3 — Real-data lessons: dandelion detection, preview fix

Lessons from the first large real-world dataset, converted to fixes.

• gephi_profile_graph now detects leaf-majority networks (most nodes with one tie) and prescribes the readable-map recipe: map the degree-2 skeleton, keep the whole graph for statistics.
• The layout guide gains a real-world harvest section: fragmentation as an expected shape, the Contraction-until-clean extent fix, arrowhead removal for directed hub maps, and legend-over-captions when communities share space.
• Gephi plugin 1.2.3 fixes preview settings silently not applying on fresh workspaces (putValue fallback) — arrow.size, edge.thickness and friends now work everywhere.

Install: gephi-ai-1.7.3.mcpb one-click for Claude Desktop; gephi-mcp-1.2.3.nbm via Tools > Plugins > Downloaded.

v1.7.1 — Explore, don't conclude

Exploration-first refinement of the opening move.

• The first reading from gephi_profile_graph is now provisional by design: impressions are offered as things to check together (never findings), every pattern is paired with a rival explanation, the opening ends with places to look rather than a plan, and verdict language waits until a check has run with the person. The profile informs the conversation; it does not conclude it.
• Applies in both the skill (Claude Code) and the tool guidance every MCP host sees.

Install: gephi-ai-1.7.1.mcpb one-click for Claude Desktop; Gephi plugin unchanged (gephi-mcp-1.2.2.nbm).

v1.7.0 — The opening move: intake + one-call graph profile

The opening-move release: every network conversation now starts with meaning and measurement.

MCP server 1.7.0 (PyPI gephi-mcp)

• New: gephi_profile_graph (tool #84). One call profiles the whole graph — size, density, degree distribution, connectivity (components, isolates), whether edge weights carry signal, plus modularity and clustering coefficient, with auto-raised flags for fragmentation, hub dominance, and layouts likely to hairball. One approval prompt instead of six, and a quantitative picture a language model reads at a glance.

Claude plugin 1.7.0

• Conversations open differently now. The skill and the /import-and-explore and /analyze-network commands start every network conversation the same way: ask in one sentence what the nodes and ties are and what the person wants to learn, run the profile, and give a plain-language first reading that combines the two. Both then guide everything downstream — the person's goal picks the metrics, size and density pick the layout, expected groupings are tested against a baseline before being used for color, isolates are asked about instead of silently removed, and clusters are captioned in the person's own vocabulary.
• The skill carries a version stamp, so an outdated installed plugin is visible in conversation (see the README's new Updating section for Claude Code, the Desktop bundle, Cowork, and the Gephi plugin).

Gephi plugin

• Unchanged (1.2.2).

Install

• Claude Desktop, one click: download gephi-ai-1.7.0.mcpb, double-click.
• Gephi plugin: gephi-mcp-1.2.2.nbm (unchanged since v1.5.2).

v1.6.0 — Similarity layout: position by role, not springs

A layout no Gephi plugin offers.

MCP server 1.6.0 (PyPI gephi-mcp)

• New: gephi_similarity_layout (tool #83). Positions nodes by the role they play in the network instead of by springs: a spectral embedding of the graph, projected to 2D and delivered through the existing positions endpoint. People who occupy similar structural positions sit together even when they are not directly connected — similarity structure that force-directed layouts cannot show. Nothing in Gephi core or the plugin portal does this.
• Works out of the box (numpy + scipy, new base dependencies). If umap-learn or scikit-learn are installed, the tool automatically uses UMAP or t-SNE for the projection; neither is required.
• The tool states its own reading rule in every result — proximity means similar role, not direct connection — and the layout guide gains the matching purpose-first row ("Who plays similar roles?").
• Run it and ForceAtlas 2 on the same graph and compare: nodes the community metric groups together but this layout separates are bridge and boundary actors.

Claude plugin 1.6.0

• Layout guide: purpose-first selection table (from 1.5.3) extended with the similarity row and reading guidance.

Gephi plugin

• Unchanged (1.2.2). The similarity layout needs no Java changes — it computes in the Python layer and pushes positions through the existing API.

Install

• Claude Desktop, one click: download gephi-ai-1.6.0.mcpb, double-click. (Bigger than previous bundles — it now carries the scientific libraries.)
• Gephi plugin: gephi-mcp-1.2.2.nbm (unchanged since v1.5.2).

v1.5.2 — Drive the whole Gephi plugin ecosystem

The plugin-ecosystem release: gephi-ai now drives Gephi's whole plugin catalog, not just its built-ins.

Gephi plugin 1.2.2 (gephi-mcp-1.2.2.nbm)

• Run any statistic by name. New /statistics/available and /statistics/run endpoints expose every StatisticsBuilder in the instance, including ones installed from the plugin portal, plus core statistics the fixed routes never covered (Stat. Inference Clustering, Weighted Degree, the Dynamic family).
• Parameters that actually reach plugin code. The generic runner sets values through setters, bare fields, and enums by name, and hands LongTask statistics a no-op progress ticket, so dialog-configured plugin metrics (verified with the CWTS Leiden Algorithm plugin) run outside their UI.
• Layout passthrough needed no changes and is now verified and documented: any installed layout plugin is listed and runnable by name (verified with Force Atlas 3D).

MCP server 1.5.2 (PyPI gephi-mcp)

• New tools gephi_list_statistics and gephi_run_statistic (82 tools total), with a working Leiden parameter recipe in the docstring.
• gephi_import_file and the skill now carry From Files to Networks recipes: spreadsheets, CSV, JSON, RDF, adjacency matrices, bipartite and similarity data all become graphs conversationally, no importer plugin required.

Claude plugin 1.5.2

• Skill sections for the plugin ecosystem (install from the portal, drive it here; Noverlap/OpenOrd/Label Adjust ship in core) and the file-format recipes.

Install

• Claude Desktop, one click: download gephi-ai-1.5.2.mcpb, double-click.
• Gephi plugin: install gephi-mcp-1.2.2.nbm via Tools > Plugins > Downloaded.

v1.5.1 — Leak-proof iterations, cold-start ergonomics

Hardening and ergonomics follow-up to v1.5.0.

Gephi plugin 1.2.1 (gephi-mcp-1.2.1.nbm)

• Exception-proof iterations. Every graph iteration in the plugin now runs over a snapshot, closing the exception-path variant of the read-hold leak fixed in 1.2.0 (an exception mid-iteration leaked the same way an early break did). The iteration rule is codified in the source next to the lock helpers.
• Degree sizing works cold. size_by_ranking / color_by_ranking by a degree column auto-compute the degree statistic instead of failing with "Column not found" on a fresh graph; missing-column errors now say how to fix them.
• Inline GEXF export. export_gexf without a file path returns the document in the response, no file round-trip.

MCP server 1.5.1 (PyPI gephi-mcp)

• gephi_export_gexf file parameter is now optional (inline mode).
• Layout guidance gives size-banded starting scalingRatio values (small graphs start at 1-2) so first layouts don't over-spread into specks.
• parse_gexf accepts a GEXF document string as well as a path.

Claude plugin 1.5.1

• The skill now tells Claude exactly how to act on the wedge detectors (graph_lock, graph_lock_stats), including saying plainly when only a Gephi restart will recover.

Install

• Claude Desktop, one click: download gephi-ai-1.5.1.mcpb, double-click.
• Gephi plugin: install gephi-mcp-1.2.1.nbm via Tools > Plugins > Downloaded.

v1.5.0 — Teaching mode: renderer pause, camera control, wedge killed at the root

The "protect the teaching mode" release. Desktop mode — watching Gephi operate while Claude narrates — is now robust and directable.

Gephi plugin 1.2.0 (gephi-mcp-1.2.0.nbm)

• Writes pause the renderer. The viz engine's own pauseUpdating()/resumeUpdating() brackets every write section (reference-counted, no-op headless), removing the read-lock pressure behind the chronic macOS wedge. Sustained write bursts under a live view now run at 1-3 ms per operation.
• A long-standing wedge source found and killed. get_nodes/get_edges with a limit smaller than the graph (the defaults) broke out of a live auto-locked graphstore iterator, permanently leaking a read hold. One queued write later, everything blocked forever while /health kept answering — the exact "healthy but hung" state seen in real sessions. The bug predates 1.0. Query endpoints now iterate a snapshot, with a JUnit regression guard.
• Nothing hangs anymore. Timed read locks, bounded UI-thread waits, and a graph_lock probe plus live graph_lock_stats counters in /health turn a wedge into an immediate, actionable error instead of an indefinite hang.
• gephi_focus_view (tool #80). Camera and attention control: fit the graph, center on a node/edge/region, select nodes visually, set zoom — Claude directs the viewer's eyes while it works.

MCP server 1.5.0 (PyPI gephi-mcp)

• New gephi_focus_view tool; health docstring documents the wedge detectors. 80 tools total.

Claude plugin 1.5.0

• New /teach command and a Teaching Mode skill section: narrated pacing, chunked layouts, camera direction, observation pauses.

Install

• Claude Desktop, one click: download gephi-ai-1.5.0.mcpb, double-click.
• Gephi plugin: install gephi-mcp-1.2.0.nbm via Tools > Plugins > Downloaded (or wait for the Plugin Portal).
• Everything else: see the README.

v1.4.0 (beta)

[1.4.0]

Added

• One-click Claude Desktop install (gephi-ai-<version>.mcpb). An MCP Bundle
  containing the server and every dependency — download from Releases, double-click,
  done. No terminal, no uv, no config file. Built reproducibly by
  scripts/build-mcpb.sh from the published PyPI artifact; runs on the system
  python3 (3.10+). The uvx/JSON-config path remains for users who prefer it.
• The viewer is now a two-way instrument. Three interactive capabilities in the
  MCP App (all verified end to end against a scripted host):
  • Click-driven exploration: clicking a node offers "Highlight connections"
    (client-side ego highlight that dims the rest of the graph) and "Ask Claude",
    which sends a question about that node into the conversation via the MCP Apps
    ui/message request — the visualization talks back.
  • Refresh from Gephi: a toolbar button re-fetches the graph through an
    app-initiated tools/call of gephi_view_graph, preserving caption settings —
    change the graph in Gephi or by asking Claude, then update the view in place.
  • Cluster captions done properly: gephi_view_graph gains caption_column and
    caption_names; the app computes size-weighted community centroids and floats
    toggleable map-style captions in an overlay — no blanked labels, no hub anchors
    (that remains gephi_label_clusters for PNG exports).
  • Time slider for dynamic GEXF: the parser now reads start/end attributes
    and <spells>; dynamic graphs get a scrubber that filters nodes and edges by
    spell containment. Numeric and date times supported.

Full changelog for 1.3.x in CHANGELOG.md. The Gephi Desktop plugin (.nbm) is unchanged since 1.1.3 and attached here for convenience.

v1.2.0 (beta)

[1.2.0]

Added

• gephi_view_graph MCP App viewer (tool #77). Returns the current graph as a
  self-contained interactive sigma.js visualization in an embedded ui:// HTML
  resource. MCP Apps hosts (claude.ai, Claude Desktop) render it inline in the
  conversation: pan/zoom, hover labels, click a node for its attributes. Graphs over
  max_nodes (default 1500) are trimmed to the highest-degree nodes, and the tool
  says so. sigma.js and graphology are vendored (MIT) so the view needs no network.
  GEXF parsing uses defusedxml (new dependency) rather than the XXE-prone stdlib
  parser.
• Public beta status called out in the README.

Changed

• The Claude Code plugin is now self-contained. Its bundled MCP config launches the
  server with uv run --directory ${CLAUDE_PLUGIN_ROOT}/../mcp-server gephi-mcp, so
  installing the plugin is the whole setup — no separate pip/pipx step, and no
  dependence on a gephi-mcp command being on the global PATH (the failure behind #4).
  uv is the one prerequisite; mcp-server/uv.lock is committed so every install
  resolves identical dependency versions.
• gephi-mcp is published to PyPI. Non-plugin MCP clients (Claude Desktop, claude mcp add, anything stdio) now use uvx gephi-mcp — fetched and cached on first run —
  or pipx install gephi-mcp. The README install docs are rewritten around this and
  PyPI classifiers were added to the package metadata.

Fixed

• pip install -e . installs dependencies again (#1, #3). The dependencies array in
  mcp-server/pyproject.toml sat below the [project.urls] table header, so TOML parsed it
  as project.urls.dependencies and the package declared no dependencies at all — installs
  either failed metadata validation or installed without mcp/httpx/pydantic. Moved it
  into the [project] table where it belongs.

Changed

• Install docs overhauled (#4 and feedback from Mathieu Jacomy). The README now points
  users at the pre-built .nbm (Releases page / repo root) instead of requiring JDK + Maven
  to build the Gephi plugin from source (build-from-source is retained as a collapsible
  alternative, with the artifact path corrected to gephi-mcp-plugin/target/). The MCP
  server install now recommends pipx so the gephi-mcp command lands on the global PATH
  where MCP clients can find it, documents the venv-PATH pitfall, and verification now
  says to confirm the server is connected via /mcp rather than which gephi-mcp. The
  Claude Code plugin install command is corrected to
  claude plugin install gephi-network-analysis@gephi-ai (#2).

[1.1.3]

A security, correctness, robustness, and test pass over the 1.0.0 baseline. Versions
1.1.1–1.1.2 were incremental build markers during the same effort (the /health
endpoint reports the version so you can confirm which jar Gephi loaded).

Security

• Removed wildcard CORS (Access-Control-Allow-Origin: *) from the plugin's HTTP
  API. It served no purpose for the local (non-browser) MCP client and was pure
  cross-origin attack surface.
• Added a Host-header guard that rejects any non-loopback host — a defense against
  DNS-rebinding attacks from a malicious web page. Requests with no Host (raw local
  clients) are still allowed.

Fixed

• macOS render deadlock (mitigated). External graph writes could deadlock Gephi's
  concurrent OpenGL VizEngine, which holds the graph read lock almost continuously while
  rendering. Writes now acquire the write lock with a non-deadlocking timed tryLock
  poll (reflected from Gephi's GraphLockImpl.writeLock) instead of the blocking
  writeLock(), and resetFilters wraps Gephi's internal setVisibleView in that lock
  so it re-enters rather than queuing. A single focused build → analyze → style → layout
  → export pass is now reliable with the live view open. The residual limit under
  sustained heavy rendering is Gephi-core (see the macOS note in the README and SKILL).
• Batch tools drop nothing. gephi_add_nodes / gephi_add_edges now apply per-item
  attributes (and edges honor directed + label), which were previously silently dropped.
• Edge directedness. Single gephi_add_edge now honors directed — undirected edges
  were always created directed.
• gephi_add_column lock ordering. It now takes the graph write lock, fixing a
  deadlock against the attribute-setters under concurrent requests.
• Ranking with negative values. color_by_ranking / size_by_ranking handle
  all-negative columns correctly (the min/max seed was Double.MIN_VALUE, the smallest
  positive double).
• Layout name matching. Names match case- and space-insensitively, so documented short
  names like forceatlas2 resolve to ForceAtlas 2.
• CSV export. Fields are quoted per RFC 4180 (separators / quotes / newlines no longer
  corrupt columns) and written as UTF-8.
• Health-check hook now actually blocks the tool (exit 2) when Gephi is unreachable,
  instead of printing a message and proceeding.
• MCP package installs again — added mcp-server/README.md so pip install no longer
  fails metadata generation on a missing readme.

Changed

• Typed MCP tools. All 76 tools expose typed, per-field parameters, so clients receive
  a precise JSON schema per tool instead of an opaque params object.
• Lifecycle hardening. Daemon HTTP listener thread + a watchdog on shutdown so the
  plugin can never block Gephi's quit.
• Configurable. GEPHI_API_URL and GEPHI_REQUEST_TIMEOUT are read from the environment.

Added

• 51 automated tests — 30 JUnit (Host-header guard, pure helpers, in-memory graph
  integration via a standalone GraphModel, and the write-lock reflection linchpin) +
  19 pytest (tool→HTTP mapping, sync-layout polling, all-76-registered regression guard) +
  2 hook tests.
• CI (.github/workflows/ci.yml) runs both suites + ruff on every push and PR.
• Complete docs: tool reference for all 76 tools, README security + macOS notes, SKILL
  working-envelope gotcha.

v0.1.0-alpha — Initial Release

The first public release of gephi-ai: AI-powered network analysis through [Gephi](https://gephi.org) and the [Model Context Protocol (MCP)](https://modelcontextprotocol.io).

This release provides a complete pipeline for building, analyzing, styling, and exporting publication-ready network visualizations by talking to your AI assistant.

What's Included

Gephi MCP Plugin

A Java NetBeans module that embeds an HTTP API server inside Gephi Desktop, exposing 73 MCP tools across 10 categories: project management, graph construction, statistics, layout, appearance, filtering, attributes, preview/export, import, and health checks.

MCP Server

A Python MCP server (built with FastMCP) that bridges any MCP-compatible AI assistant to Gephi over stdio transport. Works with Claude Code, Claude Desktop, or any other MCP client.

Claude Code Plugin

A dedicated plugin adding:

• Slash commands — /analyze-network, /community-detection, /centrality, /visualize, /import-and-explore
• Network analyst agent — a specialized subagent for structural analysis, metric comparison, and network classification
• Gephi skill — teaches Claude network science workflows, visualization best practices, and known Gephi gotchas
• Health-check hook — automatically verifies the Gephi connection before graph-modifying operations
• Reference guides — tool reference, layout guide, and statistics guide

Requirements

• Gephi Desktop 0.10.1+
• Python 3.10+
• Claude Code (for the full plugin experience) or any MCP-compatible client

Getting Started

See the [README](README.md) for installation instructions.

Architecture

Claude / AI Assistant → MCP Protocol (stdio) → MCP Server (Python) → HTTP API (localhost:8080) → Gephi Plugin (Java) → Gephi Desktop

License

Apache License 2.0

---

⚠️ Alpha release — APIs, tool signatures, and plugin interfaces may change in future versions. Feedback and bug reports are welcome via [Issues](https://github.com/MattArtzAnthro/gephi-ai/issues).