Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ VotingPlugin Control is designed to manage and troubleshoot a VotingPlugin netwo
- Run guided setup for standalone and proxy/backend networks.
- Configure common settings through searchable presets.
- Use Codex CLI or a compatible local stdio MCP client to read and preview a named backend vote site or automatic site-creation policy for up to ten explicit backends through opt-in local MCP, then review and apply it in Control. Separately grant agents scoped topology, Network Doctor checks, proxy routing previews, non-vote transport checks, and typed General Settings, Vote Sites, and Rewards editor previews. Network grants can include coordinated proxy-method previews and guided common settings, VoteLog, and Vote Party v2. See [agent setup](docs/agent-setup.md).
- Edit allowlisted nested settings and bounded lists in the Full YAML workbench, or prepare scoped MCP previews for agent-visible fields. Command lists and database pool settings remain available to browser administrators. See [configuration coverage](docs/configuration-coverage.md).
- Set up or synchronize Vote Sites while preserving existing rewards and sensitive values.
- Configure automatic Vote Site creation.
- Configure VoteLogging and retention.
Expand Down
14 changes: 14 additions & 0 deletions docs/agent-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -167,3 +167,17 @@ cannot return the complete expected diff. Each node applies its own revision and
- **Vote Party** requires both quick-setup versions and a typed v2 READ with an explicit enabled value.
It edits enablement, threshold, recipient flags and a nonblank broadcast. Legacy v1-only connectors and
inconsistent READ replies are unavailable for this agent workflow. Reward commands remain browser-managed.


## Typed managed-file fields

Grant **Read and preview typed managed-file fields** and **Track operations**. Use
`list_configuration_fields` to obtain the exact field catalog for a managed file,
`read_configuration_fields` on one authorized node, and `preview_configuration_fields` with
that read operation ID and up to eight explicit typed overrides. The status result returns only
present agent-visible values. List values are rendered as quoted lists and edits take JSON arrays.

The connector must confirm the same source revision, masked document and exact leaf paths before
browser approval. The proposal preserves all bytes outside selected values. Missing keys, ambiguous
mappings and lists with internal comments require the existing browser workflow. Commands, free-text
lists and database fields are absent from the MCP catalog. See [configuration coverage](configuration-coverage.md).
34 changes: 34 additions & 0 deletions docs/configuration-coverage.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# VotingPlugin configuration editing coverage

Use **Configuration → Full YAML → Edit typed fields** after reading the selected file. It shows the present fields
supported by the typed editor and their current values. Edit one value using JSON, review its old and new values,
then approve. MCP can list its own field catalog and preview up to eight typed changes from one scoped read. Every
typed preview checks the same node session, file revision, masked source and exact connector change paths.

| Domain | Typed browser and scoped MCP coverage | Other supported browser editing |
| --- | --- | --- |
| `Config.yml` | General Settings and guided presets, plus reminder flags, time changes, vote limits, broadcast limits, reward-world lists and other catalog fields | Full YAML and database pool size |
| `VoteSites.yml` | Named sites, editable site fields, and scalar inline reward fields through existing tools | Full YAML, split site files where supported, and existing typed reward command list editing |
| `SpecialRewards.yml` | Existing Vote Party v2 presets plus reset, eligibility and cumulative flags and values | Full YAML and typed Vote Party global, reminder and reward command lists |
| `Rewards/*.yml` | Existing named reward scalar tools on capable backends | Existing named reward and command list editors and Full YAML |
| `BungeeSettings.yml` | Existing coordinated method tooling plus per-server points and rewards, event forwarding, extra rewards and Redis TLS flags | Full YAML, global data pool size and global party command list |
| `bungeeconfig.yml` | Routing and coordinated method tooling plus broadcast scope and forwarding, wait and cache settings, scheduling and party target lists | Full YAML, pool sizes and party command lists. File changes can require a separate proxy restart |
| `GUI.yml` and `Shop.yml` | Known GUI item/URL and vote-shop appearance or behavior fields | Full YAML and selected lore lists. Named shop entries and custom layouts use Full YAML |

The catalog specifies exact fields and bounds. The typed editor works on present supported values. It rejects ambiguous
mappings and skips unsupported representations. It retains unknown fields and comments outside the replaced YAML span.
A list with comments inside its edited span stays in Full YAML. Connector comment preservation still depends on the
negotiated file contract.

The editor saves command strings as configuration for VotingPlugin's normal reward events. It has no command or reward
execution action. Review the complete command list in the browser before saving. Avoid placing credentials in command
arguments, messages or other free-text fields.

Use the existing masked browser workflow for connection settings. Typed connection tuning is limited to pool sizes.
Passwords, tokens, connection codes and keys are absent from both typed catalogs. Leave existing redaction markers
untouched to preserve secrets in the Full YAML workflow. The MCP read returns typed fields without the YAML document,
command values, approval material or connection settings.

This covers VotingPlugin configuration files already supported by the enrolled connector. It does not edit player data,
balances, vote totals, SQL tables, generated runtime files, other plugins, or host settings. Existing capability, reload,
rollback and restart reporting applies. Neither editor can trigger a process restart or deployment.
3 changes: 2 additions & 1 deletion docs/mcp-network-coverage.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ A proxy-network grant limits where an agent may use MCP. The negotiated node cap
| --- | --- | --- |
| Enrolled identity, liveness, accepted capabilities, proxy/backend presence and topology | Bounded discovery and topology, with proxy snapshot freshness and truncation indicators | Extend large-network link pagination |
| Network Doctor, overview, diagnostics, vote-site health, vote-log summary/search/trace, exact player lookup, site resolution, reward simulation | Network Doctor status and read-only observation refresh with a separate health action | Further diagnostic projections. Player and log data need separate projections and access decisions |
| Bukkit managed YAML, split VoteSites, named reward files, supported file comments, General Settings, typed Vote Sites and Rewards | Typed backend and proxy General Settings, plus a named-site guided preview and typed Vote Sites and scalar Rewards editors | Add typed editor tools using their existing validators, per-target revisions, and bounded results |
| Bukkit managed YAML, split VoteSites, named reward files, supported file comments, General Settings, typed Vote Sites and Rewards | Typed backend and proxy General Settings, plus typed managed-file fields, a named-site guided preview, and typed Vote Sites and scalar Rewards editors | Add typed editor tools using their existing validators, per-target revisions, and bounded results |
| Quick setup v1/v2, standalone/proxy setup, common settings, auto-create, vote logging, Vote Party, rewards and VoteSites sync | Named-site, automatic site creation, common settings, VoteLog and Vote Party v2 | Standalone and proxy-backend setup remain in the browser |
| Proxy routing, fixed proxy YAML, coordinated proxy-method v1/v2 and transport tests | Typed routing and coordinated method proposals with browser approval, plus a non-vote transport check | Add further curated proxy projections |
| Configuration review, apply, status, retries, durable operation history, snapshots and drift | Token-free, per-target status for operations from the same grant. Browser-only Apply. Automatic site policy supports 1–10 explicit backends with immutable revisions | Extend bounded multi-node review and partial-failure reporting to other safe typed operations |
Expand All @@ -28,6 +28,7 @@ MCP uses an opt-in server boundary, proxy-network grants, bounded discovery and
| Typed General Settings | Implemented and tested | Both node roles use the curated editor, scoped reads, exact revision and diff, and browser approval. Proxy applies report restart required |
| Typed Vote Sites editor | Implemented and tested | Exact-site read, typed add/edit, and removal for reviewable sites without inline Rewards. Revision, masked source and leaf changes checked before browser approval |
| Typed Rewards editor | Implemented and tested for supported scalar fields | Inline and named-file reward reads, exact same-scope scalar previews and browser approval. Command payloads and whole-scope edits stay in administrator workflows |
| Typed managed-file fields | Implemented and tested | Catalog-backed booleans, bounded integers, enum values and identifier lists across six files. One target and up to eight changes. Exact source/diff checks and browser approval. Command lists and database pool tuning are browser-only |
| Coordinated proxy method | Implemented and tested | Full fresh topology, exact method capability, per-peer revision, backend-first apply and explicit partial persistence. Runtime readiness and other proxy transport settings are outside the revision contract |
| VoteSites sync | Browser only pending complete diff proof | The connector can replace a destination scalar or list with a mapping while omitting the removed value from its change paths. Agent approval needs revision-matched source and destination shape evidence and a typed source projection |
| Guided common settings, VoteLog and Vote Party v2 | Implemented and tested | Both same-session READs agree on revision, key presence is reviewed, and approval checks every target's exact diff. Up to four explicit targets. Vote Party v1 and database selection stay in the browser |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
import java.util.function.Supplier;

public final class AgentOperations {
private static final Set<String> ACTIONS = Set.of("discover", "read", "preview", "status", "health", "routing", "transport", "site-policy", "site-policy-batch", "general-settings", "vote-sites-editor", "rewards-editor", "proxy-method", "common-settings", "vote-logging", "vote-party");
private static final Set<String> ACTIONS = Set.of("discover", "read", "preview", "status", "health", "routing", "transport", "site-policy", "site-policy-batch", "general-settings", "vote-sites-editor", "rewards-editor", "proxy-method", "common-settings", "vote-logging", "vote-party", "managed-fields");
private final Map<UUID, Grant> grants = new HashMap<>();
private final Map<UUID, Instant> healthRefreshes = new HashMap<>();
private final NodeRegistry registry;
Expand Down Expand Up @@ -164,6 +164,28 @@ public synchronized Map<String, Object> refreshHealth(String token, RefreshHealt
}
}

public synchronized Object managedFieldsCatalog(String token, FieldsCatalog request) {
authorize(token, "managed-fields");
return Map.of("fields", ManagedFields.catalog(request.file(), true));
}

public synchronized Object readManagedFields(String token, FieldsRead request) {
Grant grant = authorize(token, "managed-fields");
return withStableTopology(() -> {
requireNode(grant, request.nodeId());
return project(operations.readAgentManagedFields(grant.id(), request.nodeId(), request.file()));
});
}

public synchronized Object previewManagedFields(String token, FieldsPreview request) {
Grant grant = authorize(token, "managed-fields");
return withStableTopology(() -> {
requireNode(grant, request.nodeId());
return project(operations.previewAgentManagedFields(grant.id(), request.nodeId(),
parseId(request.readOperationId()), request.overrides()));
});
}

public synchronized void requireGuidedAccess(String token) {
if (authorize(token, null).actions().stream().noneMatch(Set.of("common-settings", "vote-logging", "vote-party")::contains)) {
denied();
Expand Down Expand Up @@ -563,6 +585,9 @@ public record Issue(List<String> nodeIds, List<String> actions, Integer minutes,
public record Discovery(Integer offset) { }
public record HealthRequest(List<String> nodeIds) { }
public record RefreshHealth(String nodeId) { }
public record FieldsCatalog(String file) { }
public record FieldsRead(String nodeId, String file) { }
public record FieldsPreview(String nodeId, String readOperationId, Map<String, Object> overrides) { }
public record GuidedRead(String nodeId, String preset, String evidence) { }
public record GuidedTarget(String nodeId, String presetReadId, String presenceReadId) { }
public record GuidedPreview(String preset, List<GuidedTarget> targets, Map<String, Object> overrides) { }
Expand Down
Loading
Loading