Imported from tommaone/turtleatlas-mcp (
AGENTS.md). Install upstream withnpx skills add tommaone/turtleatlas-mcp. Copyright stays with the author.
turtleatlas-mcp — MCP Knowledge Server Template
Generic MCP server serving structured knowledge (expert files, journeys, table schemas) to any LLM client.
Architecture
├── AGENTS.md ← you are here
├── index.js ← MCP server (Streamable HTTP / stdio)
├── tests/ ← test suite
├── template/ ← skeleton data (init.sh copies to resources/)
├── resources/ ← user data (gitignored except experts/)
│ ├── experts/ ← expert knowledge files (tracked)
│ ├── journeys/ ← process journeys
│ ├── tables/ ← table schema JSONs
│ └── general_db_info.md ← SQL rules
└── .opencode/skills/ ← opencode skills (add-expert, test-mcp)
What's Where
| Subfolder | Contains |
|---|---|
tests/ |
Test suite — health, session, tools, concurrency, errors, per-expert |
template/ |
Skeleton data — copied to resources/ on init |
resources/ |
User content — experts, journeys, schemas |
.opencode/skills/ |
Skills for adding experts and running tests |
Each subfolder has its own AGENTS.md with detailed instructions.
MCP Bootstrap Protocol — MANDATORY
Every agent MUST execute this before answering a user question:
Step 1: Initialize session
Call initialize on the MCP server.
Step 2: Load domain knowledge
Call list_experts — discover available expert files.
Select the one relevant to the user's question and call get_expert("<name>").
Step 3: Load rules
Call get_sql_rules — load SQL rules and domain conventions.
Step 4: Only then answer
Once you have domain expertise and rules loaded, start answering.
This protocol is not optional. Skipping it produces low-quality responses.
Tools
| Tool | Purpose |
|---|---|
list_experts |
List expert files — always call first |
get_expert |
Load a specific expert file by name |
get_sql_rules |
SQL rules and domain conventions |
list_categories |
List table categories |
get_tables_by_category |
Tables in a category (with details) |
list_tables_in_category |
Lightweight table listing for a category |
search_tables |
Full-text table search |
get_table_details |
Table schema detail from tables.zip |
list_journeys |
List journey files (optionally filtered) |
get_journey |
Load a specific journey file by name |
Working with Subagents
When spawning subagents for parallel work:
- Set
workdirto the relevant subfolder (e.g.tests/,resources/) - The subagent automatically picks up AGENTS.md in that directory
- Synthesize results when done — do NOT chain subagents into subagents
Init New Project
bash init.sh # copy template/ → resources/
npm install # install dependencies
node index.js --port=3456 # start server