Syrin

A linter + test runner for MCP servers.

---

The Problem

MCP (Model Context Protocol) is how AI agents call external tools — read files, query databases, hit APIs. If you are building or using an MCP server, your AI agent depends on those tool definitions being correct.

They usually are not.

• Tool descriptions too vague for the LLM to pick the right one
• Two tools look so similar the model picks one at random
• Parameter schemas missing or wrong — LLM hallucinates values
• A tool returns 12MB of JSON and blows the context window
• Another tool silently writes to disk when it should not
• Your logs look fine. The agent is broken.

Syrin catches all of this before production.

$ syrin analyse --transport http --url http://localhost:8000/mcp

 E110  Tool Ambiguity           get_user ↔ fetch_user
 E101  Missing Tool Description process_data has no description
 E102  Underspecified Input     user_id: no format, no example, no enum
 E105  Free Text Propagation    get_status → update_user (unconstrained string)
 W104  Generic Description      "Get data" — too vague for tool selection

 5 issues found (4 errors, 1 warning)

---

See It In Action

---

Try It Right Now

One command. No install, no config, no API keys:

npx @syrin/cli analyse --transport http --url https://docs.syrin.dev/mcp

Have your own MCP server running? Point Syrin at it:

npx @syrin/cli analyse --transport http --url http://localhost:8000/mcp

If your server uses stdio instead of HTTP:

npx @syrin/cli analyse --transport stdio --script "python server.py"

Want to try more commands against a local example server?

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 list tools --transport http --url http://localhost:8000/mcp
npx @syrin/cli analyse --transport http --url http://localhost:8000/mcp

Requirements: Node.js >= 20.12, npm >= 9

---

What Syrin Catches

Code	Issue	What Happens Without Syrin
E110	Tool Ambiguity	LLM picks the wrong tool at random
E101	Missing Description	LLM has no idea what the tool does
E102	Underspecified Input	LLM hallucinates parameter values
E105	Free Text Propagation	LLM passes sentences where data is expected
E103	Type Mismatch	Tool chains break silently
E107	Circular Dependency	Agent loops forever, burns tokens
E301	Output Explosion	12MB response blows the context window
E500	Side Effect Detected	Tool writes to disk when it should not

See the full list: Error Reference · Warning Reference

---

Commands

Command	What It Does
syrin list	Show tools, resources, and prompts a server exposes
syrin analyse	Static analysis — catch contract issues without executing tools
syrin test	Run tools in a sandbox and validate behavior against contracts
syrin dev	Interactive session — watch an LLM interact with your tools in real time
syrin doctor	Validate your config, environment, and connections

Zero-config commands: list, analyse, and test --connection work with just --url or --script. No config file needed.

Config required: dev mode needs LLM API keys. Run syrin init --global to set up once.

---

All Demos

syrin analyse Catch contract issues	syrin dev Interactive development	syrin test Sandboxed tool testing
syrin init Project setup	syrin list Inspect tools	syrin test --connection Connection test

---

Install

# Run without installing
npx @syrin/cli analyse --transport http --url http://localhost:8000/mcp

# Or install globally
npm install -g @syrin/cli
syrin --version

Set Up for a Project

syrin init                 # Creates syrin.yaml + tools/ directory
syrin doctor               # Validates config and connections
syrin analyse              # Analyse your MCP server
syrin test                 # Run contract tests
syrin dev --exec           # Interactive LLM-MCP session

Tool Contracts

Define behavioral guarantees for your tools in tools/<tool-name>.yaml:

version: 1
tool: fetch_user

contract:
  input_schema: FetchUserRequest
  output_schema: User

guarantees:
  side_effects: none
  max_output_size: 10kb

tests:
  - name: 'valid user'
    input:
      user_id: '123'
    expect:
      output_schema: User

  - name: 'invalid input'
    input:
      user_id: 123
    expect:
      error:
        type: input_validation

Run tests: syrin test or syrin test --tool fetch_user

Documentation: Writing Test Cases · Test Your MCP Tools

---

CI Integration

# .github/workflows/syrin.yml
name: MCP Validation
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g @syrin/cli
      - run: syrin analyse --ci
      - run: syrin test --ci --strict

See full CI docs: Add Syrin to CI

---

Documentation

Full docs at docs.syrin.dev

Topic	Link
Getting Started	docs.syrin.dev/getting-started
Setup Guide	docs.syrin.dev/setup
Configuration	docs.syrin.dev/configuration
All Commands	docs.syrin.dev/commands
Error Reference	docs.syrin.dev/testing/error-reference

---

Community

• Discord — Ask questions, share feedback
• GitHub Discussions — Feature ideas, show & tell
• Issues — Bug reports, feature requests

---

Contributing

Contributions welcome. See Contributing Guide and Code of Conduct.

For security issues: Security Policy.

License

ISC License. See LICENSE.

Made by Syrin Labs.