AgentTools AGENTS.md

AGENTS.md

This file provides guidance to AI agents (Claude Code, GitHub Copilot, etc.) when working with code in this repository.

Overview

AgentTools is a Wolfram Language package for integrating with AI agents and large language models. It provides MCP servers, agent skills, and other standard interfaces that enable AI systems to leverage Wolfram Language computation, Wolfram|Alpha knowledge, and related resources. The package supports a wide range of AI clients and protocols, with an extensible architecture for adding new tools, prompts, servers, and integration points.

Development

Always use the WolframLanguageContext tool when working with Wolfram Language code to ensure that you are aware of the latest documentation and other Wolfram resources.

When you make changes to paclet source code, you should also write and run tests for the changes you made using the TestReport tool and check the updated files (including test files) with the CodeInspector tool.

If you need to debug code in the WolframLanguageEvaluator tool, you'll first need to evaluate:

PacletDirectoryLoad[ "path/to/AgentTools" ];
Get[ "Wolfram`AgentTools`" ]

Note: This is not necessary for the TestReport tool, since the tests load the paclet automatically.

You should use the SymbolDefinition tool to investigate symbols rather than use things like DownValues, Definition, etc. It runs in the same kernel as the WolframLanguageEvaluator tool, so it will have access to the same definitions.

Writing and Running Tests

Use the TestReport MCP tool to run tests.

Always review testing.md for detailed instructions before modifying or adding tests.

Building the Paclet

See building.md for detailed instructions.

Code Architecture

Project Structure

• Kernel/: Contains the core implementation files
  • AgentTools.wl: Main entry point which loads an MX file if available, otherwise proceeds to Main.wl
  • Main.wl: Entry point for loading other package files; exported symbols must be declared here
  • Common.wl: Common utilities and error handling
  • CommonSymbols.wl: Any symbols shared between paclet files must be declared here
  • CreateMCPServer.wl: Implementation for creating MCP servers
  • DefaultServers.wl: Defines several predefined named MCP servers
  • DeployAgentTools.wl: Implementation for deploying and managing agent tool deployments
  • Files.wl: Helper functions for file operations (local WXF/JSON I/O plus readCloudWXF/writeCloudWXF for cloud-object WXF, used by the cloud admin API's key-label store) and the machine-wide settings store $rootPath/GlobalSettings.wxf (readGlobalSettings/getGlobalSetting/setGlobalSetting), which currently holds the usage-data opt-out
  • Formatting.wl: Definitions for formatting in notebooks
  • InstallMCPServer.wl: Implementation for installing MCP servers for use in some common MCP client applications
  • MCPClientRequests.wl: Server-to-client request infrastructure (request registry, response correlation, notification dispatch) used by MCP roots and other server-initiated requests
  • MCPRoots.wl: MCP roots handshake — issues roots/list, normalizes file:// URIs (including malformed Windows variants), and applies the selected directory to the kernel, evaluator, and RunProcess calls
  • MCPServerObject.wl: Defines the MCP server object format, including its MCPServerObject upvalues (DeleteObject, LLMConfiguration, and CloudDeploy)
  • Messages.wl: Definitions for error messages
  • PacletExtension.wl: Paclet discovery, name resolution, and definition loading for the paclet extension system
  • PreferencesContent.wl: Implementation of CreatePreferencesContent, which builds the toolset configuration UI for the system preferences dialog (see preferences-content.md)
  • Server/: MCP server implementation, split by transport so the local (stdio) and cloud (HTTP) servers share a common core
    • Server.wl: Aggregator that declares the server-session state shared across the subcontexts, defines the exported $MCPEvaluationEnvironment/$MCPTransport host descriptors (bound per session/request by each transport), and loads the children below
    • Shared.wl: Transport-agnostic core — method dispatch (handleMethod), tool/prompt resolution, tool evaluation and result formatting, capability negotiation (initResponse), server-state build (initializeServerState), environment-specific tool overrides (applyToolOverrides, driven by the "Overrides" tool property), and logging helpers
    • Local.wl: Local stdio transport — StartMCPServer, the read loop (processRequest), tool warmup, and stdout-protecting output suppression (superQuiet); calls the usage-data hooks (initializeUsageData, recordUsageData)
    • UsageData.wl: Anonymous usage data for local servers — per-session state ($mcpSessionID, $mcpClientInformation, $usageEvents), the enabling logic (SUBMIT_USAGE_DATA environment variable, otherwise the servers' "EnableUsageData" property combined with the global opt-out from GlobalSettings.wxf via getGlobalUsageDataSetting/setGlobalUsageDataSetting, which the preferences checkbox reads and writes), the session file under $rootPath/UsageData, the hourly keep-alive task, and the locked submission of finished sessions to the usage endpoint
    • Cloud.wl: Cloud HTTP transport — RunCloudMCPServer (stateless Streamable HTTP handler), CloudDeployMCPServer, the full-directory-bundle deploy implementation (cloudDeployDirectory) behind both the CloudDeploy UpValue on MCPServerObject (the UpValue itself is defined in MCPServerObject.wl) and the exported CloudDeployMCPServerBundle that deploys /mcp, the landing page, /api/info, and the forced-Private admin page/API, the self-describing session-ID capability codec, server-embedding deploy helpers (including the cloud-paclet detection — $cloudSupportPacletVersion/cloudAgentToolsAvailableQ — that swaps the heavy definition-bundling payloads for light paclet-loading ones when the connected cloud account has a new-enough Wolfram/AgentTools installed), the landing-page /api/info metadata generator, and the owner-only /api/admin key-management handler (runCloudAdminAPI: list/create/revoke PermissionsKeys) (see Cloud Deployment spec)
  • SupportedClients.wl: Registry of supported MCP clients ($SupportedMCPClients) and relevant utility functions
  • ValidateAgentToolsPacletExtension.wl: Validation of "AgentTools" paclet extensions
  • UIResources.wl: MCP Apps UI resource registry, client capability detection, and shared notebook delivery helpers (cloud deployment and experimental inline embedding)
  • Utilities.wl: General-purpose helpers — LLMKit subscription checks, Chatbook version verification, and toJSRegex for converting ICU/PCRE patterns to ECMA 262 (used when sanitizing tool schema "pattern" fields)
  • YAML.wl: YAML import/export helpers (importYAML, importYAMLString, exportYAML, exportYAMLString) used by YAML-based MCP clients (e.g. Goose)
  • Tools/: Contains several files defining predefined MCP tools used by default servers. If tool schemas are modified, we need to rebuild agent skills.
  • Prompts/: Contains files defining predefined MCP prompts used by default servers
• Assets/: Static assets bundled with the paclet
  • Apps/: HTML and JSON files for MCP Apps UI resources
  • Cloud/: Landing- and admin-page HTML/CSS/JS for cloud-deployed MCP servers — the dynamic index.html + assets/ (fetches /api/info) and the self-contained owner-only admin.html (calls /api/admin), read via PacletObject[…]["AssetLocation","Cloud"]
• FrontEnd/: FrontEnd extension resources loaded by the notebook front end
  • Assets/AgentTools.wl: Localized strings (AgentToolsStrings) and graphics (AgentToolsExpressions) used by CreatePreferencesContent (see preferences-content.md)
• Scripts/: Contains utility scripts for building, testing, and running the paclet
  • BuildAgentSkills.wls: Generates agent skill scripts from MCP tool definitions (see agent-skills.md)
  • Resources/SkillScriptTemplate.wls: Template used to generate .wls scripts for agent skills
• AgentSkills/: Agent skills for distributing Wolfram tools to AI coding agents (see agent-skills.md)
  • Manifest.wl: Maps skill names to their MCP tools and shared references
  • References/: Single-source shared reference files copied into every skill at build time
  • Skills/: Generated skill directories. The references/ and scripts/ subdirectories of each skill (e.g. AgentSkills/Skills/wolfram-language/references/) are generated by Scripts/BuildAgentSkills.wls and must not be edited manually — modify the source files (AgentSkills/References/, Scripts/Resources/SkillScriptTemplate.wls, and the corresponding tool definitions in Kernel/Tools/) and rebuild instead.
• .claude-plugin/: Claude Code plugin packaging
  • marketplace.json: Plugin marketplace definition for distributing agent skills via Claude Code
• Notes/: Development notes and design explorations
• Documentation/: Contains documentation notebooks
  • English/: English documentation
    • ReferencePages/Symbols/: Reference pages for exported symbols
    • Use the ReadNotebook tool to read documentation notebooks as markdown text
• TestResources/: Mock paclets and other test fixtures
• Tests/: Contains test files (.wlt)
• Specs/: Design specifications for features
• docs/: Developer documentation
  • testing.md: Writing and running tests
  • building.md: Building the paclet for distribution
  • error-handling.md: Error handling architecture and patterns
  • servers.md: Predefined MCP servers and choosing the right one
  • tools.md: MCP tools system, tool options, and how to add new tools
  • mcp-prompts.md: MCP prompts system and how to add new prompts
  • mcp-clients.md: MCP client support and installation
  • mcp-apps.md: MCP Apps system for interactive UI resources
  • code-inspector-rules.md: Adding custom CodeInspector rules
  • agent-skills.md: Agent skills system, build process, and how to add new skills
  • deploy-agent-tools.md: Deployment management for agent tools
  • cloud-deployment.md: Deploying an MCPServerObject as a remote HTTP MCP server in the Wolfram Cloud (CloudDeploy/CloudDeployMCPServer, directory layout, authentication, statelessness, admin key management)
  • mcp-roots.md: MCP roots handshake, working-directory propagation, and guidance for tools that resolve relative paths
  • paclet-extensions.md: Third-party paclet extension system for contributing tools, prompts, and servers
  • preferences-content.md: System preferences UI for managing deployed Wolfram toolsets
  • usage-data.md: Anonymous usage data collected by the built-in local servers ("SubmitUsageData" option, SUBMIT_USAGE_DATA, the global opt-out in GlobalSettings.wxf, storage and submission)