Contributing
How changes to XIV MCP are made, from the first test to the pull request.
XIV MCP is open source under the MIT license, and contributions are welcome: bug reports, fixes, new tools, integrations with more plugins, and improvements to this documentation.
Before you start
- Bugs: open an issue with what you asked your assistant, what happened, and the output of
/xivmcp selftest. Leave out your access token and other players' names. - New features: open an issue first and describe what players would ask for. Tools that act in the game need a permission module, capabilities and a safe way to stop, so it is worth agreeing on the shape before writing code.
The workflow
Fork and branch. Fork the repository, and create a branch from master.
Write the test first. Logic that does not need the game goes into XivMcp.Core, with an xUnit test in XivMcp.Tests that fails before your change. See Testing.
Keep the plugin thin. The code in XivMcp only adapts the core to the game: reading memory, clicking windows, drawing the UI. See Architecture.
Check it in the game. Build, let the dev plugin reload, and try your change with an assistant. Run /xivmcp selftest.
Update the documentation. This site describes every tool, permission and dependency; README.md only gives an overview and links here. Change the site in the same pull request. The tools reference updates itself from the code.
Open a pull request against master, with what changed, why, and how you tested it.
Adding a tool
A new tool of XIV MCP's own touches these places:
| Where | What |
|---|---|
XivMcp/Tools/*.cs | The definition: name, description for the assistant, input schema, ReadOnly = false if it changes something, and the handler. |
XivMcp/Plugin.cs | Registering the tool's class. |
XivMcp.Core/Permissions/PermissionCatalog.cs | The module it belongs to. Tools that drive one other plugin go into IntegrationCatalog.cs instead, with their capabilities. |
XivMcp.Core/Mcp/ToolSummaries.cs | One sentence for the player, shown in /xivmcp and in the tools reference. |
XivMcp.Core/Integrations/ToolRequirements.cs | If a core tool uses another plugin: which one, whether it is needed or only improves the tool, and what for. New plugins also go into PluginCatalog.cs, with the repository they are installed from. |
docs-site/content/docs/user/features/*.mdx | The tool table of its area, on the page players read. |
The tests check that every tool has a summary written in the player style, and that every tool in the catalog maps to an existing module.
A shortened version of get_position from XivMcp/Tools/MapTools.cs. Game.Run reads the game on the framework thread, and a ToolException reaches the assistant as its message:
yield return new McpTool
{
Name = "get_position",
Description = "Where the player is: the zone's territory id " +
"and the world position.",
Handler = (_, _) => Game.RunLoggedIn<object?>(() =>
{
var me = Svc.Objects.LocalPlayer
?? throw new ToolException(
"The character is not in the world right now.");
return new
{
territory = Svc.ClientState.TerritoryType,
position = me.Position,
};
}),
};Tools that change something set ReadOnly = false. Tools that wait are async and pass ct on, so stopping a job or the app giving up stops them too.
Writing for players
Text the player reads, in the plugin and on this site, follows a few rules:
- Plain words, short sentences. Say what happens in the game.
- No contractions: "does not", not "doesn't".
- Name costs, risks and safety behaviour, such as "Teleports cost gil" or "never during combat".
- No other plugins' names in core tool texts. Players should not be pointed to plugins they do not use. Integrations may name their own plugin.
- Tool summaries are one sentence (two when the second names a cost or safety behaviour), 100 characters at most. Reading tools start with "Looks at", "Checks", "Lists", "Finds" or "Waits".
Descriptions for the assistant are different: they cover arguments, preconditions and edge cases, and name the tools that come before or after.
Security
Never commit an access token or a local AI client configuration that contains one. Report security problems privately to the maintainer instead of in a public issue.