Trunktail includes an MCP server that exposes a Model Context Protocol interface for automating Apple Container workflows and integrating with LLM-powered automation. The server acts as a bridge between your AI tooling and the container management capabilities provided by Apple Container, enabling tasks such as listing containers and images, starting/stopping containers, and querying metadata through standardized MCP requests. You can leverage this server in your automation pipelines or chat-based assistants to perform container operations without direct UI interaction. The server adheres to the MCP protocol, making it compatible with other MCP-enabled tools and clients.

To use the MCP server, ensure the server is running (as configured by mcp_config) and connect your MCP-enabled client or CLI to the exposed endpoint. Typical interactions include requesting a list of containers, inspecting container details, and issuing start/stop/delete commands, as well as image management operations. The server translates high-level MCP intents into concrete Apple Container commands, returning structured responses that your automation can parse and act upon.

If you have custom prompts or agents, you can tailor them to issue common MCP intents such as: "list containers", "get container details <id>", "start container <id>", "pull image <name>", and "remove image <name>". The MCP protocol makes it straightforward to compose these actions across different tools and runtimes, enabling repeatable workflows for development, testing, and deployment tasks.

Prerequisites

• Node.js v18+ (or Bun 1.0+ as an alternative runtime)
• macOS (Apple Container CLI available on macOS)

Install from the repository

1. Install dependencies (choose your preferred runtime):

   • Using bun: bun install
   • Using npm/yarn: npm install

     or if you use yarn

     yarn install

2. Start the MCP server (example for Node.js path used in this repo):

   • npm script (if available): npm run start
   • Or direct execution (explicit path): node packages/mcp-server/src/index.js

3. Verify the server is running on the configured port (default 3000):

   • You should see a listening message in the console or a healthy endpoint check via MCP client.

Optional: Configure environment variables

• PORT: Port the MCP server should listen on (default 3000)
• MCP_PROTOCOL_VERSION: Protocol version to advertise/use (default 1)

Notes

• If you use Bun, you can rely on bun install and bun run to start any scripts defined in the project.
• If the repository provides a containerized or packaged runtime, prefer that method per the project’s docs.

Tips and common issues:

• Environment variables: Ensure PORT is not blocked by your firewall and is exposed to your MCP clients.
• Protocol version: Confirm MCP protocol compatibility if you integrate with third-party MCP clients; mismatches may lead to handshake failures.
• Path accuracy: The start path in mcp_config should point to the actual entry file for the MCP server in your deployment. Adjust as needed if your build outputs to dist/ or lib/.
• macOS Apple Container: This MCP server serves the Apple Container backend; ensure the host system has the necessary CLI tools and permissions to manage containers/images.
• Logging: Increase log verbosity temporarily if troubleshooting by adding verbose flags or environment variables as supported by the server implementation.