# Asimonim ![A vintage Israeli phone token (asimon), captured mid-drop as it falls into a payphone coin slot](./logo.png) [![codecov](https://codecov.io/gh/bennypowers/asimonim/graph/badge.svg)](https://codecov.io/gh/bennypowers/asimonim) A high-performance design tokens parser, validator, and language server, available as a CLI tool and Go library. > *Asimonim* (אֲסִימוֹנִים) (ahh-see-moh-NEEM) is Hebrew for "[tokens](https://www.wikiwand.com/en/articles/Telephone_token)". Design systems use [design tokens][dtcg] to store visual primitives like colors, spacing, and typography. Asimonim parses and validates token files defined by the Design Tokens Community Group (DTCG) specification, supporting both the current draft and the stable V2025_10 schema. ## Features - **Multi-schema support**: Handles both Draft and V2025_10 DTCG schemas - **Automatic schema detection**: Duck-typing detection of schema version from file contents - **Alias resolution**: Resolve token references with cycle detection - **Multi-format export**: Convert tokens to TypeScript, SCSS, Swift, XML, and more - **CSS output**: Generate CSS custom properties from tokens - **Search**: Find tokens by name, value, or type with regex support - **Validation**: Check files for schema compliance and circular references - **Language Server**: Full LSP support for design tokens in your editor - **MCP Server**: Model Context Protocol server for AI-assisted development ## Installation ### npm ```bash npm install -g @pwrs/asimonim ``` ### Gentoo Linux Enable the `bennypowers` overlay, then install: ```bash eselect repository enable bennypowers emaint sync -r bennypowers emerge dev-util/asimonim ``` ### From Source ```bash go install bennypowers.dev/asimonim@latest ``` ## Documentation Full documentation is available at **[bennypowers.dev/asimonim](https://bennypowers.dev/asimonim/)**. - [Quick Start](https://bennypowers.dev/asimonim/docs/quick-start/) - [Editor Integration](https://bennypowers.dev/asimonim/docs/editors/) - [LSP Features](https://bennypowers.dev/asimonim/docs/lsp/) - [Configuration](https://bennypowers.dev/asimonim/docs/configuration/) - [CLI Reference](https://bennypowers.dev/asimonim/docs/reference/commands/) - [Schema Versions](https://bennypowers.dev/asimonim/docs/reference/schemas/) ## Go library The module is `bennypowers.dev/asimonim`. The main public packages are: | Package | Purpose | | --- | --- | | `parser` | Parse DTCG JSON and YAML into tokens | | `resolver` | Resolve aliases and `$extends` relationships | | `token` | Core token types and prefix-aware lookup | | `schema` | Schema version detection and conversion | | `validator` | Schema consistency checks | | `convert` | Serialize tokens to CSS, SCSS, JS, Swift, Android XML, and other formats | | `load` | High-level loading from paths and package specifiers | | `fs` | Filesystem abstraction | | `config` | Configuration loading | | `version` | Build and version information | The module also exports `specifier`, `parser/common`, `lsp`, and `mcp`, but the packages above are the primary library surface. Run `go doc bennypowers.dev/asimonim/parser` (or the name of any package above) for the full API and examples. ### Embedding the MCP server `mcp.Register` mounts asimonim's tools and resources on an MCP server that you own: ```go import ( asimonimmcp "bennypowers.dev/asimonim/mcp" "github.com/modelcontextprotocol/go-sdk/mcp" ) srv := mcp.NewServer(&mcp.Implementation{Name: "my-server", Version: "1.0.0"}, nil) _, err := asimonimmcp.Register(srv, filesystem, cfg, cwd, asimonimmcp.WithTools(asimonimmcp.Selection{Exclude: []string{"convert_tokens"}}), asimonimmcp.WithConflictPolicy(asimonimmcp.ConflictError), ) if err != nil { return err } ``` With no options, `Register` mounts the full surface and replaces existing entries, matching `NewServer`. `WithTools`, `WithResources`, and `WithTemplates` take exact, case-sensitive `Include` and `Exclude` lists. An `Include` entry that matches nothing is an error; an `Exclude` entry that matches nothing is ignored. `ConflictError` and `ConflictSkip` inspect the host server through a short-lived in-memory session when there are selected features to check, so host session hooks and middleware observe that probe. `ConflictError` returns a `*RegistrationConflict` that lists the conflicting tools, resources, and templates. A server returned by `Register` has no transport of its own, so `Run` returns an error. #### Workspace resolution Tools and resources resolve their workspace lazily, in this order: 1. an explicit `cfg` passed to `NewServer` or `Register`; 2. a directory passed with `WithWorkspace`, which is shared by every session and never queries roots; 3. the session's cached resolution; 4. the client's MCP roots: directly on protocol revisions before `2026-07-28`, and through multi-round-trip requests (SEP-2322) on `2026-07-28` and later; 5. the server's `cwd`. Each session caches its own resolution, so one embedding server can serve clients with different roots. Stateless Streamable HTTP deployments create a new session per request, so roots are resolved on every call; use `WithWorkspace` there to avoid the extra round trip. `WithWorkspace` cannot be combined with an explicit config: `Register` rejects that combination. The MCP server targets `go-sdk` v1.8.0, which supplies the multi-round-trip primitives used on `2026-07-28`. Every completed tool and resource result carries its provenance in `_meta`: ```json { "_meta": { "asimonim/workspace": { "root": "/path/to/workspace", "source": "roots", "warning": "optional explanation of a cwd fallback" } } } ``` `source` is one of `explicit-config`, `host`, `roots`, or `cwd`. `warning` is present when an advertised roots request fails or returns unusable data, such as an empty list or an invalid URI. A client that does not advertise roots falls back to cwd without a warning. Warnings are also logged once per resolution with a dedicated `slog` handler on stderr, so stdout stays reserved for JSON-RPC. ### Version information ```go import ( "fmt" "bennypowers.dev/asimonim/version" ) fmt.Println(version.Get()) fmt.Println(version.Info()["gitCommit"]) ``` `Get` returns the injected or detected version, `Info` returns a structured map for diagnostics, and `Full` includes the Git commit when available. ### Compatibility policy The module is pre-1.0 (`0.x`). While it remains at `0.x`: - Minor releases can include breaking changes to public package APIs. We call out such changes in the release notes. - Patch releases are backwards compatible within the same minor version. - Pin exact versions, for example `go get bennypowers.dev/asimonim@v0.3.3`. Do not rely on floating ranges or on compatibility across minor versions. - Once the module reaches `1.0`, we will follow semantic versioning and make breaking changes only in major releases. Everything under `internal/` is not public API. ### Input formats Asimonim parses [DTCG][dtcg] documents. Style Dictionary JSON is not DTCG. Its keys omit the `$` prefix (`value` and `type` instead of `$value` and `$type`), and composite values such as shadows and typography use shapes that differ from DTCG. References use the same `{group.token}` syntax in both formats, but that does not make the surrounding document DTCG. Normalize Style Dictionary output into DTCG before passing it to asimonim. The parser does not translate Style Dictionary files. ## Contributing See [CONTRIBUTING.md][contributingmd] ## License GPL-3.0-or-later [dtcg]: https://design-tokens.github.io/community-group/format/ [contributingmd]: ./CONTRIBUTING.md