aias-spec

Parse AIAS (AI Annotation Standard) comments from JavaScript/TypeScript source and generate a working MCP server.

This is a utility for developers who want to hand-author AI-facing semantics (@ai:action, @ai:param, @ai:confirms, …) above real functions and get an MCP tool surface without writing an OpenAPI contract first.

What is an AIAS @ai: annotation?

An @ai: annotation is a block of @ai:* comments written directly above a real function that describe what it does and how an AI should call it — its action type, parameters, and a human-readable confirmation line.

The flow:

1. You annotate a real function with @ai:* comments.
2. aias generate parses those comments and emits a working MCP server that wraps the function as a callable tool.
3. An MCP host — Claude Desktop, or any MCP client — loads that server and can now call the function as a tool, using the schema and description taken straight from your annotations.

The point: it gets you from "I have a function" to "an AI can call this function" without hand-writing an MCP server or an OpenAPI spec first.

Full annotation reference: docs/ANNOTATIONS.md.

Requirements

• Node.js 20+

Install

npm install -g aias-spec
# or from this repo
npm install
npm run build
npx aias --help

Quick start

aias init
# edit aias.config.json — set appName and include globs
aias generate

Annotate a function:

/**
 * @ai:app name="habit-tracker" version="1.0.0" compliance="basic"
 * @ai:action type="add_habit" synonyms="add habit,track new habit"
 * @ai:param name="habit" type="string" hint="Name of the habit"
 * @ai:confirms "Added habit `{habit}` to your list."
 */
export async function addHabit(habit: string) {
  // your implementation
}

aias generate writes a build artifact (default generated/mcp-server.ts). Treat it like protobuf or GraphQL codegen output — regenerate in CI, do not hand-edit or commit it as source of truth.

Commands

| Command | Description | |---------|-------------| | aias init | Create aias.config.json | | aias generate | Parse → validate → emit MCP server | | aias generate -c path/to/config.json | Use a custom config path |

Config (aias.config.json)

| Field | Default | Notes | |-------|---------|-------| | appName | (required) | MCP server name | | namespace | "ai" | Scan @ai: or a custom prefix e.g. "acme" → @acme: | | include | src/**/*.ts, src/**/*.tsx | Glob(s) to scan | | exclude | tests, node_modules, dist | Glob(s) to skip | | outputPath | generated/mcp-server.ts | Generated file path |

Validation

Generation fails loud with file:line errors when:

• @ai:param names do not match the real function signature
• @ai:confirms {placeholders} do not match declared params
• Tags are malformed or unknown
• Required attributes are missing

@ai:private functions are never emitted as MCP tools.

@ai:requires is descriptive metadata only — the generated server does not enforce auth or other preconditions.

Supported patterns

aias-spec scans for @ai: annotations on three JS/TS shapes:

• Standalone exported functions (export function foo() {}, export async function foo() {})
• Exported const arrow/function-expression bindings (export const foo = () => {}, export const foo = async () => {})
• Class methods (class X { foo() {} })

Not yet supported — annotations on these will be silently skipped (no functions parsed, no error):

• Object-literal method shorthand ({ foo() {} })
• Class field arrow functions (class X { foo = () => {} })

If your annotation isn't picking up, check your function is one of the three supported shapes above. Broader coverage may come in a later version.

Compliance levels

• Basic — full working invocation (tool → call your function).
• Standard (@ai:callback, @ai:status) — schema + stub handlers with an explicit TODO: wire this to your app's actual event transport. Transport is outside AIAS; the generator will not pretend to auto-wire it.
• Full (@ai:widget, …) — out of scope for this package.

Examples and E2E

npm test          # unit tests (parser / validate / generate)
npm run e2e       # habit-tracker example → MCP Client invoke

See examples/habit-tracker/ and docs/BENCHMARK.md.

MCP SDK version policy

@modelcontextprotocol/sdk is pinned in this package’s dependencies (currently 1.29.0). When MCP ships a breaking revision, bump deliberately, re-run the test suite, and document the change in the release notes. Generated servers inherit that pin via their own project dependency on the SDK.

License

MIT — see LICENSE.