ACL MCP Server

A Model Context Protocol (MCP) server that provides Agent Communication Language (ACL) support for AI agents. This server enables AI assistants to understand and execute structured ACL commands for development workflows, knowledge management, and agent customization.

What is ACL?

Agent Communication Language (ACL) is a Domain-Specific Language (DSL) designed for concise, structured communication with AI agents. It provides:

Simple syntax: Easy-to-learn scope.action(details) pattern
Development workflow automation: Streamline common development tasks
Knowledge management: Persist information across sessions
Agent customization: Define project-specific behaviors and commands

Example ACL commands:

fix("failing tests")                    # Fix issues
refactor("auth module", "extract logic") # Refactor code
test("integration/**")                   # Run tests
project.build()                          # Build project

Features

This MCP server provides:

get_acl_specification tool: Retrieve the complete ACL specification document
instructions://acl-specification resource: Access ACL documentation for agent context
Comprehensive ACL support: Full implementation of ACL v1.1 specification
Built-in caching: Optimized performance for repeated ACL specification access

Installation

As an MCP Server

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "acl": {
      "command": "npx",
      "args": ["-y", "@lacolaco/acl@latest"]
    }
  }
}

Available Tools and Resources

Tools

`get_acl_specification`

Retrieves the complete ACL specification document.

Use cases:

When users ask about ACL syntax or commands
When encountering ACL expressions like begin(), finish(), project.build()
When working with ACL object methods like ACL.init(), ACL.load()
Understanding workflow automation patterns

Example:

// Tool returns the full ACL.md specification
{
  "content": [
    {
      "type": "text",
      "text": "# Agent Communication Language (ACL)\n\n## Version 1.1..."
    }
  ]
}

Resources

`instructions://acl-specification`

Provides the ACL specification as an instruction resource for agent context.

Properties:

Name: "ACL Specification for AI Agents"
MIME Type: text/markdown
Content: Complete ACL specification document

This resource is automatically loaded by MCP clients to provide agents with ACL knowledge.

ACL Specification Highlights

The server provides access to the complete ACL v1.1 specification, which includes:

Core Syntax

scope.action(details)

Global Functions

fix(issue) - Analyze and fix problems
refactor(targets, direction) - Refactor code safely
think(issue) - Read-only analysis (no file modifications)
test(pattern?) - Run tests
alert(message) - Alert about violations
note(message) - Save to USER_INSTRUCTION_FILE
docs(targets) - Enhance documentation

Built-in Objects

ACL - System management (init, load, scan, list)
project - Current project context
session - Current conversation

Declaration Syntax

obj objectName = "description" - Declare objects
fn functionName(params): returnType { ... } - Define functions

For complete details, see the ACL.md specification.

Development

Prerequisites

Node.js 18+
pnpm 10+

Commands

# Install dependencies
pnpm install

# Start development server
pnpm start

# Run tests
pnpm test

# Build for production
pnpm build

# Format code
pnpm format

# Inspect MCP server (with MCP Inspector)
pnpm inspect

# Inspect built server
pnpm inspect:dist

Project Structure

acl-mcp-server/
├── src/
│   ├── main.ts              # Entry point
│   ├── mcp-server.ts        # MCP server factory
│   ├── tools/               # Tool definitions
│   │   └── get-acl-specification.ts
│   ├── resources/           # Resource definitions
│   │   └── acl-instructions.ts
│   └── utils/               # Shared utilities
│       └── acl-path.ts      # ACL specification loader
├── ACL.md                   # ACL specification
├── CLAUDE.md                # Project instructions for Claude
└── dist/                    # Build output

Testing

The project uses Vitest for testing:

# Run all tests
pnpm test

# Type check only
pnpm run typecheck

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests to the GitHub repository.

License

MIT

@lacolaco/acl

Quick Install