TAAL - Tooling & Agent Abstraction Layer

TAAL provides a single source of truth for your MCP (Model Context Protocol) server configurations and Agent Skills, automatically syncing them across all your AI coding tools.

Quick Start

# Install globally
npm install -g @anaclumos/taal

# Initialize TAAL
taal init

# Edit ~/.taal/config.yaml with your MCP servers

# Sync to all providers
taal sync

Installation

Via npm (recommended)

npm install -g @anaclumos/taal

Via bunx

bunx @anaclumos/taal --help

From source

git clone https://github.com/anaclumos/taal.git
cd taal
bun install
bun run src/index.ts --help

Commands

taal init

Initialize TAAL configuration in ~/.taal/.

taal init
taal init --force  # Overwrite existing config

Creates:

• ~/.taal/config.yaml - Your unified configuration
• ~/.taal/skills/ - Directory for Agent Skills
• ~/.taal/backups/ - Automatic backups before sync

taal collect

Import existing MCP server configurations from installed providers.

taal collect

Scans all installed providers and merges their MCP configs into your TAAL config. Warns about conflicts when the same server name has different configurations across providers.

taal validate

Validate your TAAL configuration.

taal validate

Checks:

• YAML syntax
• Schema validation
• Undefined environment variables
• Mutual exclusivity (stdio vs HTTP)

Exit codes:

• 0 - Valid configuration
• 1 - Invalid configuration

taal diff

Preview what would change without writing.

taal diff              # Show changes for all providers
taal diff cursor       # Show changes for specific provider

Shows:

• + Servers to be added
• - Servers to be removed
• ~ Servers to be modified

Exit codes:

• 0 - No changes
• 1 - Changes detected

taal sync

Sync MCP configs and skills to providers (CORE COMMAND).

taal sync              # Sync to all enabled providers
taal sync cursor       # Sync to specific provider

What it does:

1. Reads ~/.taal/config.yaml
2. Transforms servers to provider-specific formats
3. Creates backups of existing configs
4. Writes new configs atomically
5. Copies skills to provider directories

taal list

List configured MCP servers and skills.

taal list

Shows:

• All configured MCP servers (stdio/http)
• All discovered skills
• Enabled providers

taal providers

List all supported providers.

taal providers

Shows for each provider:

• Installation status
• Enabled/disabled status
• Config file path
• Config format (json/yaml/toml)

Configuration

Config File: ~/.taal/config.yaml

version: "1"

mcp:
  # TAAL MCP server (requires bun: https://bun.sh)
  taal:
    command: bunx
    args: ["--bun", "taal-mcp"]

  # Stdio server example
  filesystem:
    command: bunx
    args: ["--bun", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
    env:
      LOG_LEVEL: "info"
  
  # HTTP server example
  context7:
    url: https://mcp.context7.com/mcp
    headers:
      CONTEXT7_API_KEY: "${CONTEXT7_API_KEY}"

skills:
  paths:
    - ~/.taal/skills
    - ~/projects/my-custom-skills

providers:
  enabled:
    - claude-desktop
    - cursor
    - zed

Environment Variables

Use ${VAR_NAME} syntax to reference environment variables:

mcp:
  my-server:
    command: npx
    env:
      API_KEY: "${MY_API_KEY}"

TAAL will:

• Substitute variables at sync time
• Warn if variables are undefined
• Keep original ${VAR} syntax if undefined

Provider-Specific Overrides

mcp:
  my-server:
    command: npx
    args: ["-y", "server"]
    overrides:
      codex:
        enabled_tools: ["tool1", "tool2"]
        startup_timeout_sec: 60

TAAL MCP Server

TAAL can run as an MCP server to expose its CLI features as tools. Requires Bun.

mcp:
  taal:
    command: bunx
    args: ["--bun", "taal-mcp"]

Tools exposed:

• taal_init
• taal_config_read
• taal_collect (collects and writes to ~/.taal/config.yaml)
• taal_mcp_add
• taal_mcp_delete
• taal_skill_path_add
• taal_skill_path_delete
• taal_validate
• taal_diff
• taal_sync
• taal_list
• taal_providers

Supported Providers

TAAL supports 9 AI coding assistants:

Provider	Config Format	Config Path	Skills Support
Claude Desktop	JSON	~/Library/Application Support/Claude/claude_desktop_config.json	✅ ~/.claude/skills/
Claude Code	JSON	~/.claude/settings.json	✅ ~/.claude/skills/
Cursor	JSON	~/Library/Application Support/Cursor/User/settings.json	❌
Continue.dev	YAML	~/.continue/config.yaml	❌
Zed	JSON	~/.config/zed/settings.json	❌
OpenCode	JSON	~/.config/opencode/opencode.json	✅ .opencode/skills/
Codex	TOML	~/.codex/config.toml	✅ ~/.codex/skills/
Windsurf	JSON	Provider-specific path	❌
Antigravity	JSON	Provider-specific path	❌

Provider-Specific Notes

Claude Desktop

• Only supports stdio servers (no HTTP)
• Skills directory: ~/.claude/skills/

Claude Code

• Supports both stdio and HTTP servers (SSE deprecated)
• Uses type: "http" | "stdio" format in config
• Skills directory: ~/.claude/skills/
• Can import servers from Claude Desktop via claude mcp add-from-claude-desktop

Cursor

• Only supports stdio servers
• macOS: ~/Library/Application Support/Cursor/User/settings.json
• Linux: ~/.config/Cursor/User/settings.json

Continue.dev

• Supports both stdio and HTTP (SSE)
• Transforms ${VAR} to ${{ secrets.VAR }}

Zed

• Uses context_servers key (not mcpServers)
• Supports both stdio and HTTP

OpenCode

• Command as array: ["npx", "-y", "package"]
• Uses environment instead of env
• Explicit type: "local" | "remote"

Codex

• TOML format with [mcp_servers.name] sections
• Uses http_headers for HTTP servers
• Supports enabled_tools filtering

Windsurf

• Supports streamable-http transport for HTTP servers

Antigravity

• Only supports stdio servers

Agent Skills

TAAL syncs Agent Skills to providers that support them.

Skill Structure

~/.taal/skills/
└── my-skill/
    ├── SKILL.md          # Required: YAML frontmatter + instructions
    ├── scripts/          # Optional: Helper scripts
    └── references/       # Optional: Reference materials

SKILL.md Format

---
name: My Skill
description: What this skill does
version: 1.0.0
---

# My Skill

Instructions for the AI agent...

Skill Discovery

TAAL discovers skills from all paths in skills.paths:

skills:
  paths:
    - ~/.taal/skills
    - ~/projects/custom-skills
    - /shared/team-skills

Skill Validation

TAAL validates:

• SKILL.md exists
• YAML frontmatter is valid
• name field is present

Invalid skills are skipped with warnings.

Workflow Examples

First-time setup

# 1. Initialize TAAL
taal init

# 2. Import existing configs
taal collect

# 3. Validate merged config
taal validate

# 4. Preview changes
taal diff

# 5. Sync to all providers
taal sync

Adding a new MCP server

# 1. Edit config
vim ~/.taal/config.yaml

# 2. Validate
taal validate

# 3. Preview changes
taal diff

# 4. Sync
taal sync

Adding a new skill

# 1. Create skill directory
mkdir -p ~/.taal/skills/my-skill

# 2. Create SKILL.md
cat > ~/.taal/skills/my-skill/SKILL.md << 'EOF'
---
name: My Skill
---

Instructions...
EOF

# 3. Verify skill is discovered
taal list

# 4. Sync to providers
taal sync

Syncing to specific provider

# Only sync to Cursor
taal sync cursor

# Preview changes for Zed
taal diff zed

Backup & Safety

TAAL automatically creates backups before every write:

~/.taal/backups/
├── claude_desktop_config.json.2024-01-15T10-30-00-000Z.backup
├── settings.json.2024-01-15T10-30-00-001Z.backup
└── config.toml.2024-01-15T10-30-00-002Z.backup

Backups are timestamped and never overwritten.

Troubleshooting

Config validation fails

# Check detailed errors
taal validate

# Common issues:
# - Missing required fields
# - Both command and url specified (mutual exclusivity)
# - Invalid YAML syntax

Sync fails for a provider

# Check if provider is installed
taal providers

# Check if provider is enabled
cat ~/.taal/config.yaml | grep -A 10 "providers:"

# Try syncing just that provider
taal sync cursor

Skills not syncing

# Verify skills are discovered
taal list

# Check skill paths in config
cat ~/.taal/config.yaml | grep -A 5 "skills:"

# Verify SKILL.md format
cat ~/.taal/skills/my-skill/SKILL.md

Environment variables not substituted

# Check if variable is set
echo $MY_VAR

# TAAL will warn about undefined variables
taal validate

Development

Prerequisites

• Bun v1.2.19 or later

Setup

git clone https://github.com/user/taal.git
cd taal
bun install

Running tests

bun test                    # All tests
bun test tests/commands/    # Command tests only
bun test tests/integration/ # Integration tests only

Running locally

bun run src/index.ts --help
bun run src/index.ts init

Project structure

taal/
├── src/
│   ├── index.ts           # CLI entry point
│   ├── commands/          # CLI commands
│   ├── config/            # Config parsing & validation
│   ├── providers/         # Provider implementations
│   ├── skills/            # Skills handling
│   └── utils/             # Shared utilities
├── tests/
│   ├── commands/          # Command tests
│   ├── config/            # Config tests
│   ├── providers/         # Provider tests
│   ├── skills/            # Skills tests
│   └── integration/       # End-to-end tests
└── taal.schema.json       # JSON Schema for IDE support

Publishing

TAAL uses automated NPM publishing via GitHub Actions, triggered by GitHub Releases.

Release Process

1. Update version in package.json:

   npm version patch  # 1.0.0 -> 1.0.1
   npm version minor  # 1.0.0 -> 1.1.0
   npm version major  # 1.0.0 -> 2.0.0
   

2. Commit and push:

   git add package.json
   git commit -m "chore: bump version to v1.0.1"
   git push origin main
   

3. Create a GitHub Release:

   • Go to GitHub → Releases → "Create a new release"
   • Create a new tag (e.g., v1.0.1)
   • Add release notes
   • Click "Publish release"

4. GitHub Actions automatically:

   • Runs tests
   • Runs linter
   • Publishes to NPM with provenance

Prerequisites

Repository maintainers must configure:

• NPM trusted publishing (OIDC) - no NPM_TOKEN needed
• NPM account with 2FA enabled
• Package access permissions

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Write tests for new functionality
4. Ensure all tests pass: bun test
5. Ensure linter passes: bun x ultracite check
6. Submit a pull request

Adding a new provider

1. Create src/providers/my-provider.ts
2. Implement the Provider interface
3. Register in src/providers/my-provider.ts: registry.register(new MyProvider())
4. Add tests in tests/providers/my-provider.test.ts
5. Update this README

License

MIT

Links

• NPM Package
• GitHub Repository
• Issue Tracker
• MCP Specification
• Agent Skills Specification

Acknowledgments

Built with:

• Bun - Fast JavaScript runtime
• Commander.js - CLI framework
• Zod - Schema validation
• YAML - YAML parsing
• Chalk - Terminal colors