@syrin/cli 1.4.0 → 1.4.1

package/README.md

@@ -1,99 +1,131 @@
 # Syrin
 
-![Syrin Logo](/assets/syrin-logo-dark-bg.png)
+![Syrin Logo](https://github.com/Syrin-Labs/cli/raw/main/assets/syrin-logo-dark-bg.png)
 
-[![npm version](https://badge.fury.io/js/%40syrin%2Fsyrin.svg)](https://badge.fury.io/js/%40syrin%2Fsyrin) [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC) [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
+[![npm version](https://badge.fury.io/js/%40syrin%2Fcli.svg)](https://www.npmjs.com/package/@syrin/cli) [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC) [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.12.0-brightgreen)](https://nodejs.org/)
 
-**Syrin is a runtime intelligence system for MCP servers.**
+## Stop Silent Failures in AI Tool Calls
 
-It helps developers **see, validate, and reason about MCP execution** before systems reach production.
+Your AI agent just called the same tool 47 times with identical parameters.
+Your logs look fine. You're silently burning $200 in tokens.
 
-Documentation: [https://docs.syrin.dev](https://docs.syrin.dev)
+**Syrin catches these failures before production.**
 
 ---
 
-## The Problem
+## What Is This?
 
-Building MCP servers today usually looks like this:
+Syrin is a development toolkit for [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) servers — the standard way AI agents call external tools.
 
-1. Define tools and prompts
-2. Connect an LLM
-3. Run the server
-4. Hope execution behaves as expected
+**Without Syrin:**
 
-When things go wrong:
+```txt
+Tool called 47x          →  No visibility
+$200 burned              →  Silent failure
+Logs look "fine"         →  Debug for hours
+```
 
-- Tools are called for unclear reasons
-- Behaviour changes between runs
-- Debugging relies on logs and guesswork
-- Contract issues surface only after failures
+**With Syrin:**
 
-Most problems are discovered **after** deployment.
+```txt
+Loop detected at call #3 →  Execution halted
+Full event trace         →  See exactly what happened
+Contract validated       →  Catch issues before runtime
+```
 
 ---
 
-## Installation
+## What Syrin Catches
 
-### Quick start
+**Tool Loops** — Model proposes the same tool repeatedly with no progress
 
-```bash
-npx @syrin/cli init
-```
+**Wrong Tool Selection** — Similar names, overlapping schemas, ambiguous descriptions cause silent misbehavior
 
-### Global install
+**Silent Failures** — Tool throws an error but execution continues with broken state
 
-```bash
-npm install -g @syrin/cli
-```
+**Contract Mismatches** — Input/output schemas don't align between chained tools
 
-### Local install (recommended for CI)
+**Hidden Dependencies** — Tools assume state that doesn't exist
 
-```bash
-npm install @syrin/cli
-```
+Documentation: [https://docs.syrin.dev](https://docs.syrin.dev)
 
-Requirements:
+---
 
-- Node.js ≥ 18
-- npm ≥ 9
+## See It In Action
+
+<table>
+<tr>
+<td width="33%"><strong>syrin analyse</strong><br/>Catch contract issues</td>
+<td width="33%"><strong>syrin dev</strong><br/>Interactive development</td>
+<td width="33%"><strong>syrin test</strong><br/>Sandboxed tool testing</td>
+</tr>
+<tr>
+<td><img src="https://github.com/Syrin-Labs/cli/raw/main/assets/demo/syrin-analyse/analyse.gif" width="280" alt="syrin analyse demo"/></td>
+<td><img src="https://github.com/Syrin-Labs/cli/raw/main/assets/demo/syrin-dev/dev.gif" width="280" alt="syrin dev demo"/></td>
+<td><img src="https://github.com/Syrin-Labs/cli/raw/main/assets/demo/syrin-test/test_tool.gif" width="280" alt="syrin test demo"/></td>
+</tr>
+<tr>
+<td width="33%"><strong>syrin init</strong><br/>Project setup</td>
+<td width="33%"><strong>syrin list</strong><br/>Inspect tools</td>
+<td width="33%"><strong>syrin test --connection</strong><br/>Connection test</td>
+</tr>
+<tr>
+<td><img src="https://github.com/Syrin-Labs/cli/raw/main/assets/demo/syrin-init/init.gif" width="280" alt="syrin init demo"/></td>
+<td><img src="https://github.com/Syrin-Labs/cli/raw/main/assets/demo/syrin-list/list.gif" width="280" alt="syrin list demo"/></td>
+<td><img src="https://github.com/Syrin-Labs/cli/raw/main/assets/demo/syrin-test/test_connection.gif" width="280" alt="syrin test --connection demo"/></td>
+</tr>
+</table>
 
 ---
 
-## The Syrin Way
+## Try It Now
+
+```bash
+# No install needed — run directly
+npx @syrin/cli analyse --transport http --url http://localhost:8000/mcp
+```
+
+Or install globally:
 
-Syrin changes the workflow.
+```bash
+npm install -g @syrin/cli
 
-Instead of guessing how MCP behaves, you **inspect and validate it explicitly**.
+syrin init --global
+syrin doctor                                                    # Check your environment
+syrin analyse --transport http --url http://localhost:8000/mcp   # Analyze an MCP server
+syrin dev --exec --transport http --url http://localhost:8000/mcp # Interactive dev mode
+```
 
-**Before:**
+Or initialize a project with local config:
 
-```text
-Write tools → Connect LLM → Run server → Debug via logs
+```bash
+npx @syrin/cli init
+syrin doctor
+syrin analyse
 ```
 
-**With Syrin:**
+**Want to try with a sample server?** Clone the repo and use the included [example MCP server](./examples/demo-mcp-py/):
 
-```text
-Define tools
-→ Analyse contracts
-→ Validate protocol
-→ Inspect behaviour interactively
-→ Enable execution with confidence
+```bash
+git clone https://github.com/Syrin-Labs/cli.git && cd cli/examples/demo-mcp-py
+python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt
+python server.py --mode http --port 8000 &
+npx @syrin/cli analyse --transport http --url http://localhost:8000/mcp
 ```
 
-Syrin does not replace MCP.  
-It makes MCP systems understandable and testable.
+Requirements: Node.js >= 20.12, npm >= 9
 
 ---
 
-## What Syrin Does
+## Core Commands
 
-- Validates MCP protocol compliance
-- Analyses tool contracts statically
-- Lets you interact with MCP servers using real LLMs
-- Shows which tools are proposed and why
-- Prevents accidental execution by default
-- Surfaces configuration and contract errors early
+| Command | What It Does |
+|---------|--------------|
+| `syrin analyse` | Static analysis — catches contract issues before runtime |
+| `syrin dev` | Interactive mode — see exactly what your LLM proposes |
+| `syrin test` | Contract testing — validate tools in sandboxed execution |
+| `syrin doctor` | Environment check — validate config and connections |
+| `syrin list` | Inspect tools, resources, and prompts from your server |
 
 ---
 
@@ -115,7 +147,7 @@ syrin config setup --global
 syrin config edit-env --global
 
 # Use Syrin from any directory
-syrin dev --exec --transport http --mcp-url http://localhost:8000/mcp
+syrin dev --exec --transport http --url http://localhost:8000/mcp
 ```
 
 ### Configuration Management
@@ -135,133 +167,82 @@ See the [Configuration Guide](docs/Commands/syrin-config.md) for more details.
 
 ## Key Capabilities
 
-### Static Tool Contract Analysis (`syrin analyse`)
+### `syrin analyse` — Find Problems Before They Hit Production
 
-LLMs rely entirely on tool contracts.  
-If contracts are vague or incomplete, behaviour becomes unreliable.
+**The Problem:** Your LLM picks the wrong tool, or calls tools with missing parameters. You only find out after deployment when users report broken behavior.
 
-`syrin analyse` inspects:
-
-- Tool definitions
-- Parameter schemas
-- Description clarity
-- Implicit dependencies between tools
-
-This catches issues **before runtime**.
+**The Solution:** Static analysis of your tool contracts catches issues before any code runs.
 
 ```bash
-syrin analyse
+syrin analyse           # Check all tool contracts
+syrin analyse --ci      # Exit code 1 on errors (for CI pipelines)
+syrin analyse --strict  # Treat warnings as errors
 ```
 
-This is especially useful in CI:
-
-```bash
-syrin analyse --ci
-```
+**What it catches:**
+- Vague or missing tool descriptions
+- Parameters without descriptions (LLMs guess wrong)
+- Overlapping tools that confuse model selection
+- Schema mismatches between chained tools
+- Circular dependencies
 
 ---
 
-### Interactive Execution Inspection (`syrin dev`)
+### `syrin dev` — See What Your LLM Actually Does
 
-`syrin dev` provides a governed chat interface for MCP servers.
+**The Problem:** Your LLM calls tools, but you can't see *why* it chose that tool, what parameters it's sending, or what happens between steps. You're debugging blind.
 
-- Preview tool calls before execution
-- Execute tools only when explicitly enabled
-- Switch between LLM providers
-- Inspect large tool outputs safely
+**The Solution:** An interactive environment where you see every tool proposal before it executes.
 
 ```bash
-syrin dev
+syrin dev         # Preview mode (no execution)
+syrin dev --exec  # Enable execution when ready
 ```
 
-Enable execution only when ready:
-
-```bash
-syrin dev --exec
-```
+**What you get:**
+- See exactly which tool the LLM wants to call and why
+- Inspect parameters before they're sent
+- Step through tool chains one call at a time
+- Full event trace of every decision
 
 ---
 
-### Tool-Level Structural Safety Validation (`syrin test`)
+### `syrin test` — Validate Tools in Isolation
 
-**v1.3.0 Feature**: `syrin test` now validates tool contracts through sandboxed execution.
+**The Problem:** A tool works fine in manual testing, but in production it has side effects you didn't expect, returns massive outputs that blow your context window, or behaves differently on repeated calls.
 
-This acts as a "hard design gate" to ensure each tool is individually safe for agent-driven systems:
-
-- **Tool Unit Contracts**: Define behavioral guarantees in `tools/<tool-name>.yaml` files
-- **Sandboxed Execution**: Tools tested in isolated environments with resource limits
-- **Behavioral Observation**: Detects side effects, non-determinism, output explosions, hidden dependencies
-- **Process Reuse**: Optimized for performance (100+ tools in 1-3 minutes)
+**The Solution:** Sandboxed execution that validates each tool against its behavioral contract.
 
 ```bash
-# Validate all tools
-syrin test
-
-# Test specific tool
-syrin test --tool fetch_user
-
-# Strict mode (warnings become errors)
-syrin test --strict
-
-# JSON output for CI
-syrin test --json
+syrin test                 # Test all tools
+syrin test --tool fetch_user  # Test specific tool
+syrin test --strict        # Warnings become errors
+syrin test --json          # JSON output for CI
 ```
 
-**Connection Testing** (legacy behavior):
-
-```bash
-syrin test --connection
-```
-
-### Protocol and Configuration Validation
-
-Before running anything, Syrin validates assumptions.
+**What it catches:**
+- Unexpected side effects (file writes, network calls)
+- Non-deterministic outputs
+- Output size explosions
+- Hidden dependencies on external state
+- Contract violations
 
-```bash
-syrin doctor
-syrin test --connection  # Test MCP connection only
-```
+---
 
-These commands ensure:
+### `syrin doctor` — Validate Your Setup
 
-- Configuration is valid
-- Environment variables are set
-- MCP protocol is followed correctly
+**The Problem:** Something's misconfigured, but you're not sure what. API keys? Transport settings? MCP connection?
 
----
-
-## Typical Workflow
+**The Solution:** A single command that checks everything.
 
 ```bash
-syrin init        # Initialise configuration
-syrin doctor      # Validate setup
-syrin analyse     # Static analysis of tool contracts
-syrin test        # Validate tool contracts (sandboxed execution)
-syrin test --connection  # Test MCP protocol connection
-syrin dev         # Inspect behaviour interactively
+syrin doctor              # Check config, env, connections
+syrin test --connection   # Test MCP connection only
 ```
 
-This workflow is designed to catch issues **before production**.
-
 ---
 
-## Commands Overview
-
-| Command                   | Purpose                                       |
-| ------------------------- | --------------------------------------------- |
-| `syrin init`              | Initialise a Syrin project                    |
-| `syrin doctor`            | Validate configuration and environment        |
-| `syrin analyse`           | Static analysis of MCP tool contracts         |
-| `syrin test`              | Validate tool contracts (sandboxed execution) |
-| `syrin test --connection` | Test MCP protocol connection (legacy)         |
-| `syrin list`              | Inspect tools, resources, and prompts         |
-| `syrin dev`               | Interactive execution inspection              |
-
-Full documentation: [https://docs.syrin.dev/commands](https://docs.syrin.dev/commands)
-
----
-
-## Tool Contracts (v1.3.0)
+## Tool Contracts
 
 Define behavioral guarantees for your tools in `tools/<tool-name>.yaml` files:
 
@@ -282,17 +263,12 @@ See [Tool Contracts Documentation](./docs/tool-contracts.md) for details.
 
 ## Configuration
 
-Syrin uses a single configuration file:
+Syrin supports **two configuration layers**:
 
-```bash
-syrin.yaml
-```
+- **Local** (`syrin.yaml` in project root) — transport, MCP connection, LLM providers
+- **Global** (`~/.syrin/syrin.yaml`) — shared LLM API keys and defaults across projects
 
-This file defines:
-
-- Transport type (`stdio` or `http`)
-- MCP server connection
-- Allowed LLM providers
+Local config overrides global config. CLI flags override both.
 
 Configuration reference: [https://docs.syrin.dev/configuration](https://docs.syrin.dev/configuration)
 
@@ -322,17 +298,37 @@ Provider configuration: [https://docs.syrin.dev/configuration/llm](https://docs.
 
 ---
 
+## Community
+
+- [Discord](https://discord.gg/j8GUvHybSa) — Ask questions, share feedback
+- [GitHub Discussions](https://github.com/Syrin-Labs/cli/discussions) — Feature ideas, show & tell
+- [Documentation](https://docs.syrin.dev) — Full guides and API reference
+
+Found a bug or have a feature request? [Open an issue](https://github.com/Syrin-Labs/cli/issues) — we read every one.
+
+If Syrin helped you catch something your logs missed, a [star on GitHub](https://github.com/Syrin-Labs/cli) helps others find it too.
+
+---
+
 ## Links
 
 - Documentation: [https://docs.syrin.dev](https://docs.syrin.dev)
-- GitHub: [https://github.com/syrin-labs/cli](https://github.com/syrin-labs/cli)
-- Issues: [https://github.com/syrin-labs/cli/issues](https://github.com/syrin-labs/cli/issues)
+- GitHub: [https://github.com/Syrin-Labs/cli](https://github.com/Syrin-Labs/cli)
+- Issues: [https://github.com/Syrin-Labs/cli/issues](https://github.com/Syrin-Labs/cli/issues)
 - npm: [https://www.npmjs.com/package/@syrin/cli](https://www.npmjs.com/package/@syrin/cli)
 
 ---
 
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md) before submitting PRs.
+
+For security issues, please see our [Security Policy](SECURITY.md).
+
+---
+
 ## License
 
-ISC License. See LICENSE for details.
+ISC License. See [LICENSE](LICENSE) for details.
 
-Made with ❤️ by **Syrin Labs**.
+Made with care by **Syrin Labs**.

package/dist/cli/commands/dev.d.ts

@@ -17,8 +17,8 @@ export interface DevCommandOptions {
     runScript?: boolean;
     /** Transport type override */
     transport?: 'stdio' | 'http';
-    /** MCP URL override (for http transport) */
-    mcpUrl?: string;
+    /** MCP server URL override (for http transport) */
+    url?: string;
     /** Script command override (for stdio transport) */
     script?: string;
 }

package/dist/cli/commands/dev.js

@@ -60,7 +60,7 @@ export async function executeDev(options = {}) {
         try {
             const configResult = loadConfigWithGlobal(projectRoot, {
                 transport: options.transport,
-                mcp_url: options.mcpUrl,
+                mcp_url: options.url,
                 script: options.script,
             });
             config = configResult.config;
@@ -82,14 +82,14 @@ export async function executeDev(options = {}) {
                     log.info('💡 Using global config requires CLI flags:');
                     log.info('   --transport <stdio|http>');
                     if (options.transport === 'http') {
-                        log.info('   --mcp-url <url>');
+                        log.info('   --url <url>');
                     }
                     else if (options.transport === 'stdio') {
                         log.info('   --script <command>');
                     }
                     else {
                         // Show both options when transport is not specified
-                        log.info('   --mcp-url <url> (for http transport)');
+                        log.info('   --url <url> (for http transport)');
                         log.info('   --script <command> (for stdio transport)');
                     }
                     log.blank();

package/dist/cli/index.js

@@ -297,7 +297,7 @@ export function setupCLI() {
         .option('--event-file <path>', 'Directory path for event files (default: .syrin/events). Events are saved as {sessionId}.jsonl')
         .option('--run-script', 'Run script to spawn server internally. If not provided, stdio uses script automatically, http connects to existing server')
         .option('--transport <type>', 'Transport type (stdio or http). Required when using global config.')
-        .option('--mcp-url <url>', 'MCP server URL (required for http transport when using global config)')
+        .option('--url <url>', 'MCP server URL (required for http transport when using global config)')
         .option('--script <command>', 'Script command to run MCP server (required for stdio transport when using global config)')
         .action(async (options) => {
         try {
@@ -309,7 +309,7 @@ export function setupCLI() {
                 eventFile: options.eventFile,
                 runScript: options.runScript || false,
                 transport: options.transport,
-                mcpUrl: options.mcpUrl,
+                url: options.url,
                 script: options.script,
             });
         }

package/dist/config/merger.js

@@ -50,7 +50,7 @@ export function createConfigFromGlobal(global, flags = {}) {
     }
     // Validate transport-specific requirements
     if (flags.transport === 'http' && !flags.mcp_url) {
-        throw new Error('MCP URL is required for HTTP transport. Use --mcp-url <url> flag.');
+        throw new Error('MCP URL is required for HTTP transport. Use --url <url> flag.');
     }
     if (flags.transport === 'stdio' && !flags.script) {
         throw new Error('Script command is required for stdio transport. Use --script <command> flag.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syrin/cli",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Syrin is a runtime intelligence system that makes MCP servers debuggable, testable, and safe to run in production.",
   "type": "module",
   "main": "dist/index.js",
@@ -23,7 +23,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.12.0"
   },
   "keywords": [
     "mcp",
@@ -55,52 +55,52 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/syrin-labs/cli.git"
+    "url": "git+https://github.com/Syrin-Labs/cli.git"
   },
   "author": "Syrin Labs Team",
   "license": "ISC",
   "bugs": {
-    "url": "https://github.com/syrin-labs/cli/issues"
+    "url": "https://github.com/Syrin-Labs/cli/issues"
   },
-  "homepage": "https://github.com/syrin-labs/cli#readme",
+  "homepage": "https://github.com/Syrin-Labs/cli#readme",
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
     "@types/inquirer": "^9.0.9",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^25.0.3",
-    "@types/react": "^19.2.7",
+    "@types/node": "^25.2.0",
+    "@types/react": "^19.2.10",
     "@types/uuid": "^10.0.0",
-    "@typescript-eslint/eslint-plugin": "^8.52.0",
-    "@typescript-eslint/parser": "^8.52.0",
-    "@vitest/coverage-v8": "^3.2.4",
-    "@vitest/ui": "^3.2.4",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/ui": "^4.0.18",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-typescript": "^4.4.4",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-prettier": "^5.5.4",
-    "globals": "^17.0.0",
-    "prettier": "^3.7.4",
+    "eslint-plugin-prettier": "^5.5.5",
+    "globals": "^17.3.0",
+    "prettier": "^3.8.1",
     "tsc-alias": "^1.8.16",
     "tsconfig-paths": "^4.2.0",
     "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+    "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.71.2",
-    "@apidevtools/json-schema-ref-parser": "^15.1.3",
-    "@modelcontextprotocol/sdk": "^1.25.1",
-    "commander": "^14.0.2",
+    "@anthropic-ai/sdk": "^0.72.1",
+    "@apidevtools/json-schema-ref-parser": "^15.2.2",
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "commander": "^14.0.3",
     "ink": "^6.6.0",
     "ink-text-input": "^6.0.0",
-    "inquirer": "^13.1.0",
+    "inquirer": "^13.2.2",
     "js-yaml": "^4.1.1",
     "ollama": "^0.6.3",
-    "openai": "^6.15.0",
-    "react": "^19.2.3",
+    "openai": "^6.17.0",
+    "react": "^19.2.4",
     "uuid": "^13.0.0",
-    "zod": "^4.3.5"
+    "zod": "^4.3.6"
   }
 }