tokenlite-mysql-mcp AGENTS.md

🤖 AI Agents Guide: TokenLite MySQL MCP

Notice to LLMs, Agents, and Coding Assistants: If you are reading this file, you have been connected to the TokenLite MySQL MCP Server. This server is heavily protected and optimized to prevent hallucinations, reduce context window bloat, and block dangerous operations.

Tool names are prefixed with the database name (e.g., mydb_search_schema, mydb_execute_safe_query). If a custom TOOL_PREFIX is set, that prefix is used instead.

You MUST follow the rules below strictly.

🚨 Golden Rules

1. NEVER use SHOW TABLES or DESCRIBE manually.

   • Rule: You MUST use the search_schema tool instead.
   • Why: search_schema provides a compressed, heuristic-based Graph (Auto-Join Context) that gives you the DDL of the requested table and its implicitly related tables. It also injects business semantics from metadata.json.

2. NEVER manually query information_schema.

   • Rule: If a query fails because of a missing column or table (e.g., ER_BAD_FIELD_ERROR), you MUST use the refresh_schema tool to rebuild the internal graph, and then use search_schema again. Do not attempt to query information_schema directly.

3. NEVER write business metrics SQL manually (when templates are configured).

   • Rule: If templates.json is loaded, search_schema will include a reminder to use the query_templates prompt before writing analytical SQL (e.g., LTV, Revenue, Active Users).
   • Why: The company has predefined, vetted SQL templates. Hallucinating metrics leads to incorrect dashboards.

4. DO NOT add LIMIT to your exploratory queries.

   • Rule: When using execute_safe_query, the server will automatically inject a LIMIT at the AST level (default: MCP_QUERY_ROW_LIMIT=500). Do not manually append LIMIT unless you need a very specific offset pagination.
   • Truncation: If results reach the applied LIMIT, the CSV output includes a -- rows: N (truncated at LIMIT X) footer. Do not assume you have the full dataset.