@decaf-ts/with-ai

v2.9.0

Published

4 days ago

Expose decaf-ts related skills and agents for selected decaf-ts developers, plus a lightweight MCP and CLI path for future tooling.

0High
0Medium
0Low

tvenceslau

vnogueira91

plantuml mermaid uml drawio mddocs md jsdoc doc docs documentation test reports confluence ci/cd ci cd template typescript ts agents skills mcp cli with-ai decaf-ts

Typescript Template

This repository is meant to provide an enterprise template for any standard Typescript project

Licence GitHub language count GitHub top language

Open Issues Closed Issues Pull Requests

Forks Stars Watchers

Documentation here, Test results here and Coverage here

Description

@decaf-ts/with-ai is the decaf-ts AI tooling package: the authoritative catalog of decaf skills and agents, plus a lightweight MCP server and a decaf with-ai CLI module.

Skills & agents catalog — the canonical markdown content under skills/ and agents/, consumed by AI harnesses and by Paperclip orchestration;
MCP server — a detached Model Context Protocol server exposing jira, xray and common tooling, booted with decaf with-ai mcp or the decaf-mcp bin (see MCP server setup). Clients are built per tool request (credentials load lazily and never break boot), destructive tools are gated by a server-level policy, and the Streamable HTTP transport is bearer-token authenticated and loopback-bound by default;
CLI commands — decaf with-ai mcp (boot the MCP server), decaf with-ai encrypt-assets (build-time encryption of AI-value content for the public npm artifact) and decaf with-ai install-skills (decrypt packaged skills and symlink them into an AI harness).

Usage details live in How to Use and in the with-ai CLI & MCP server tutorial section. The design rationale and delivered architecture are documented in the DECAF-51 specification record and the architecture handbook (workdocs/ai/project/ in the decaf-ts umbrella checkout).

How to Use

MCP server setup

@decaf-ts/with-ai ships an MCP server that any MCP client can launch through npx. There are two ways to start it:

| Launch | Command | Presets / --read-only | Notes | | --- | --- | --- | --- | | decaf-mcp binary | npx -y @decaf-ts/with-ai@latest | No: always every module except agents, read and write | Simplest form. | | decaf with-ai mcp | npx -y -p @decaf-ts/cli@latest -p @decaf-ts/utils@latest -p inquirer -p @decaf-ts/with-ai@latest decaf with-ai mcp [--preset <list>] [--read-only] | Yes | Requires BANNER=false in the server env: without it the CLI prints a banner to stdout and corrupts the stdio JSON-RPC stream. @decaf-ts/utils and inquirer are listed explicitly because the currently published packages do not declare them as runtime dependencies. |

Credentials are read lazily, per tool call: the server always boots, and a tool whose variables are missing returns a clear error while the server keeps running.

Presets

--preset takes a comma-separated list. common (the with-ai-ping health check) is always included. Without --preset, every module except agents is registered. --read-only keeps only tools annotated readOnlyHint: true, across every selected preset.

| Preset | Tools (read-only) | What it exposes | Required env | | --- | --- | --- | --- | | common | 1 (1) | with-ai-ping | none | | jira | 21 (7) | Jira issues, search, comments, transitions, ticket templates | JIRA_HOST, JIRA_EMAIL, JIRA_API_TOKEN | | xray | 4 (1) | Xray manual-test steps | XRAY_HOST, XRAY_CLIENT_ID, XRAY_CLIENT_SECRET + the Jira set | | agiletest | 4 (1) | AgileTest test steps | AGILE_TEST_HOST, AGILE_TEST_CLIENT_ID, AGILE_TEST_CLIENT_SECRET + the Jira set | | crawl4ai | 3 (3) | Page to HTML, screenshot, PDF (SSRF-guarded) | CRAWL4AI_URL (CRAWL4AI_TOKEN optional) | | searxng | 1 (1) | Metasearch | SEARXNG_URL | | docconvert | 2 (0) | Office/text/URL to PDF (Gotenberg) | DOCCONVERT_URL | | paperclip | 21 (9) | Paperclip instance API for member copilots | PAPERCLIP_BASE_URL, PAPERCLIP_API_KEY, PAPERCLIP_COMPANY_ID | | agents (opt-in) | 0 tools, 46 prompts | Each decaf agent as an MCP prompt | ENCRYPTION_KEY |

Tool counts exclude with-ai-ping and were measured against version 2.5.1.

Environment variables

| Variable | Used by | Required | Description | | --- | --- | --- | --- | | JIRA_HOST | jira, xray, agiletest | yes | Jira Cloud host, e.g. your-org.atlassian.net (https:// is added when missing). | | JIRA_EMAIL | jira, xray, agiletest | yes | Atlassian account email. | | JIRA_API_TOKEN | jira, xray, agiletest | yes | Atlassian API token. | | JIRA_PROJECT_KEYS | jira | no | Comma-separated project allowlist, e.g. ABC,XYZ. Unset means every project is allowed. | | JIRA_DEFAULT_PROJECT_KEY | jira | no | Project used when a create request omits it; must be inside the allowlist. | | JIRA_DEFAULT_ISSUE_TYPE | jira | no | Issue type used when a create request omits it. | | JIRA_RATE_LIMIT_RETRY_DELAY_MS | jira | no | Delay before retrying a rate-limited call (default 3000). | | XRAY_HOST | xray | yes | Xray API host, e.g. xray.cloud.getxray.app. | | XRAY_CLIENT_ID / XRAY_CLIENT_SECRET | xray | yes | Xray API key pair. | | AGILE_TEST_HOST / AGILE_TEST_CLIENT_ID / AGILE_TEST_CLIENT_SECRET | agiletest | yes | AgileTest API host and key pair. | | CRAWL4AI_URL / CRAWL4AI_TOKEN | crawl4ai | URL yes, token no | Crawl4AI endpoint and optional bearer token. | | SEARXNG_URL | searxng | yes | SearXNG endpoint. | | DOCCONVERT_URL | docconvert | yes | Gotenberg endpoint. | | PAPERCLIP_BASE_URL / PAPERCLIP_API_KEY / PAPERCLIP_COMPANY_ID | paperclip | key yes | Paperclip API base (e.g. http://127.0.0.1:3100/api), agent API key, company UUID. | | ENCRYPTION_KEY | agents, jira ticket templates | for those | Decrypts the packaged content. Distributed out-of-band; never commit it. | | MCP_DESTRUCTIVE_POLICY | all | no | confirm (default: destructive tools need confirm: true), allow, or block. Read per call. | | BANNER | decaf with-ai mcp | yes for stdio | Set to false. | | WITH_AI_CONTENT_ROOT | agents, templates | no | Absolute path searched before the packaged content. | | WITH_AI_MCP_TOKEN / MCP_HOST / MCP_PORT | http transport | token yes | Bearer token, bind address (default 127.0.0.1), port (default 3111). |

Client configurations

Each profile below shows the same server for Claude Code (JSON: a project .mcp.json, or claude mcp add-json <name> '<server object>') and Codex (TOML: ~/.codex/config.toml). Replace every <...> placeholder. Claude Code also expands ${VAR} in .mcp.json, so you can reference secrets from your shell instead of writing them into the file.

The decaf-mcp binary: every module except agents, read and write. Set only the variables for the services you use; a tool whose credentials are missing fails on call, never at boot.

Claude Code (.mcp.json):

{
  "mcpServers": {
    "with-ai": {
      "command": "npx",
      "args": [
        "-y",
        "@decaf-ts/with-ai@latest"
      ],
      "env": {
        "JIRA_HOST": "your-org.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "<jira-api-token>",
        "JIRA_PROJECT_KEYS": "ABC,XYZ",
        "XRAY_HOST": "xray.cloud.getxray.app",
        "XRAY_CLIENT_ID": "<xray-client-id>",
        "XRAY_CLIENT_SECRET": "<xray-client-secret>",
        "AGILE_TEST_HOST": "<agiletest-host>",
        "AGILE_TEST_CLIENT_ID": "<agiletest-client-id>",
        "AGILE_TEST_CLIENT_SECRET": "<agiletest-client-secret>",
        "PAPERCLIP_BASE_URL": "http://127.0.0.1:3100/api",
        "PAPERCLIP_API_KEY": "<paperclip-agent-api-key>",
        "PAPERCLIP_COMPANY_ID": "<company-uuid>",
        "CRAWL4AI_URL": "http://localhost:11235",
        "CRAWL4AI_TOKEN": "",
        "SEARXNG_URL": "http://localhost:8080",
        "DOCCONVERT_URL": "http://localhost:3000",
        "ENCRYPTION_KEY": "<encryption-key>",
        "MCP_DESTRUCTIVE_POLICY": "confirm"
      }
    }
  }
}