Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add instructions/jvm/usql-mcp/agents-mdgit clone --depth 1 https://github.com/jvm/usql-mcpWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/instructions/jvm/usql-mcp/agents-md)<a href="https://agentmods.dev/instructions/jvm/usql-mcp/agents-md"><img src="https://agentmods.dev/badge/instructions/jvm/usql-mcp/agents-md.svg" alt="Measured on agentmods" height="20"></a>What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5 | $0.05700 | $0.05700 |
| Opus 5 | $0.02850 | $0.02850 |
| Sonnet 5 | $0.01140 | $0.01140 |
| Haiku 4.5 | $0.00570 | $0.00570 |
Grade B, and why
usql-mcp AGENTS.md scanned grade B with 2 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 3d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Unrestricted tool accessmediumExcessive agency
A wildcard tool grant or "run any command" leaves no least-privilege boundary at all.
- `usql-mcp:tools:*` - Individual tool execution Runs shell commandslowCapability
Expected in a hook, worth knowing in a rule or an instructions file.
subprocess.kill("SIGTERM"); How it starts
The opening of the file, as written. The whole thing — 717 lines — stays where its author put it; the contents beside it link to each section on GitHub.
AGENTS.md
This file provides guidance to coding agents when working with code in this repository.
Repository Overview
This repository implements a full-featured MCP Server (Model Context Protocol Server) that exposes usql capabilities to AI assistants and LLM applications. The server enables AI models to execute SQL queries and inspect database schemas across any database system supported by usql, with enterprise-ready features including background execution, progress tracking, query safety validation, schema resources, SQL workflow prompts, and performance optimizations.
Key Responsibilities:
- Safely bridge user queries to usql CLI execution
- Handle connection strings with credential sanitization
- Parse and validate results with safety analysis
- Manage long-running queries with background execution
- Provide schema browsing via MCP resources
- Offer SQL workflow templates via MCP prompts
- Track progress for long operations
- Cache schema data for performance
- Rate limit requests for security
Development Language & Stack
The project is implemented in TypeScript/Node.js with the following core dependencies:
- @modelcontextprotocol/sdk: Official SDK for building MCP servers (v1.x)
- usql: Invoked as an external CLI process (must be installed system-wide)
- node-sql-parser: For query validation and safety analysis
- Other standard Node.js utilities for process execution and error handling
Project Structure
usql-mcp/
├── src/
│ ├── index.ts # MCP server initialization with all capabilities
│ ├── tools/ # MCP Tools (8 tools)
│ │ ├── execute-query.ts # Execute SQL queries with safety analysis
│ │ ├── execute-script.ts # Execute multi-statement scripts
│ │ ├── list-databases.ts # List available databases
│ │ ├── list-tables.ts # List tables in a database
│ │ ├── describe-table.ts # Get table schema details
│ │ ├── get-job-status.ts # Check background job status
│ │ ├── get-server-info.ts # Get server configuration and stats
│ │ ├── cancel-job.ts # Cancel running background jobs
│ │ ├── background-wrapper.ts # Background execution wrapper
│ │ └── output-schemas.ts # Tool output JSON schemas
│ ├── resources/ # MCP Resources
│ │ ├── index.ts # Resource handlers registration
│ │ ├── list-resources.ts # List available resources
│ │ ├── read-resource.ts # Read resource content
│ │ └── uri-parser.ts # sql:// URI parsing
│ ├── prompts/ # MCP Prompts
│ │ ├── index.ts # Prompt system exports
│ │ ├── prompt-registry.ts # Central prompt registry
│ │ └── templates/ # SQL workflow templates
│ │ ├── analysis.ts # Performance & quality prompts
│ │ ├── migration.ts # Migration & documentation prompts
│ │ └── debugging.ts # Optimization & debugging prompts
│ ├── usql/ # Core execution layer
│ │ ├── process-executor.ts # Spawn and manage usql subprocesses
│ │ ├── parser.ts # Parse usql output into structured data
│ │ ├── connection.ts # Connection string validation
│ │ ├── config.ts # Configuration management
│ │ ├── job-manager.ts # Background job tracking and cleanup
│ │ └── database-mapper.ts # Database-specific command mapping
│ ├── notifications/ # MCP Notifications
│ │ ├── progress-notifier.ts # Progress reporting for long operations
│ │ └── list-changed-notifier.ts # ListChanged notifications
│ ├── cache/ # Performance caching
│ │ └── schema-cache.ts # TTL-based schema caching
│ ├── utils/ # Shared utilities
│ │ ├── error-handler.ts # Consistent error formatting
│ │ ├── logger.ts # Debug logging
│ │ ├── query-safety-analyzer.ts # Query risk analysis
│ │ ├── query-validator.ts # Query syntax validation
│ │ ├── config-validator.ts # Configuration validation
│ │ ├── rate-limiter.ts # Request rate limiting
│ │ ├── request-tracker.ts # Request cancellation tracking
│ │ └── pagination.ts # Cursor-based pagination
│ └── types/
│ └── index.ts # Shared TypeScript interfaces
├── dist/ # Compiled JavaScript output
├── tests/
│ ├── integration/ # Tests requiring usql installation
│ │ ├── execute-query.sqlite.test.ts # SQLite query execution
│ │ ├── resources.test.ts # Resource browsing
│ │ └── process-executor.usql.test.ts # usql subprocess integration
│ └── unit/ # Unit tests (519 tests total)
│ ├── tools.test.ts # All tool handlers
│ ├── background-wrapper.test.ts # Background execution
│ ├── job-manager.test.ts # Job lifecycle management
│ ├── query-safety-analyzer.test.ts # Safety analysis
│ ├── progress-notifier.test.ts # Progress reporting
│ ├── pagination.test.ts # Pagination utilities
│ ├── request-tracker.test.ts # Request cancellation
│ ├── prompts/ # Prompt system tests
│ │ └── prompt-registry.test.ts # Prompt registration and retrieval
│ └── resources/ # Resource system tests
│ ├── list-resources.test.ts # Resource listing
│ └── uri-parser.test.ts # URI parsing
├── package.json
├── tsconfig.json
├── .npmrc
├── README.md
└── CLAUDE.md (this file)
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 3d ago First seen · 717 lines · 5,700 tokens per session scan B 9ff49d105bf6
usql-mcp AGENTS.md is an instructions file published in the GitHub repository jvm/usql-mcp (3 stars, last pushed 6mo ago), licensed MIT. It adds 5,700 tokens to every session, about $0.0285 per session on Opus 5. A static security scan graded it B with 2 findings (unrestricted tool access, runs shell commands). No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.
Other instructions, from other repositories
js-bson AGENTS.md
Instructions for mongodb/js-bson, covering agents.md, project overview, commands, benchmarks and structure.
mail-time CLAUDE.md
Instructions for veliovgroup/mail-time, covering claude.md, what this repo is, where to look first, mental model for changes and common pitfalls to avoid.
js-bson CLAUDE.md
Instructions for mongodb/js-bson, a project described as: BSON Parser for node and browser.
skills AGENTS.md
Instructions for qdrant/skills, covering qdrant skills, project overview, project structure, navigating skills locally and conventions.
Silex AGENTS.md
AGENTS.md instructions for silexlabs/Silex, covering agents.md, tech stack, run it locally, building the desktop app and when writing code for silex (editing source).
plan-forge database.instructions.md
Database patterns for .NET — Dapper/EF Core, parameterized queries, migration strategy.