AI keeps hallucinating my component syntax — here's how I fixed it with MCP

I thought AI coding assistants would just work. Then I asked an agent to write a generic list component for my framework, qingkuai. It handed me back a file that looked perfectly fine — until I dropped it into the project and it failed to compile.

The tags were wrong. The template syntax was borrowed from Svelte. The slot context was passed in a way .qk files don't support at all.

A few correction cycles later, it finally worked. The problem wasn't the model — it was that the agent had zero context about qingkuai's syntax and was guessing from memory.

That's why I built qingkuai-mcp-server.

---

What happens when an AI agent meets a private syntax

AI writes React and Vue fluently because there's plenty of training data. But with a framework that has its own component file format, the agent falls back on what it knows:

• It mixes in template habits from other frameworks (Svelte, Vue SFCs)
• It misses framework-specific conventions: embedded script tags, slot context auto-inference, generic parameters on components
• It produces code that looks correct but doesn't compile — the worst kind of bug

The root cause isn't model quality. It's a missing information channel.

---

What the qingkuai MCP server provides

qingkuai-mcp-server exposes four tools that agents can call directly:

Tool	What it does
search_qingkuai_docs	Look up .qk syntax rules
check_qingkuai_syntax	Validate .qk file structure
compile_qingkuai	Compile to JavaScript and verify the output
format_qingkuai_code	Format a component file

This isn't about stuffing syntax docs into a system prompt. It's about giving the agent active tools it can call when it's uncertain — look up, then write, then verify.

---

Why .qk files specifically need this

Without external context, an agent typically produces something like this:

<script lang="ts">
    export let list: string[] = []
</script>

{#each list as item}
    <slot item={item} />
{/each}

Direction is roughly right. But that's Svelte syntax — it won't compile in a qingkuai project.

The correct .qk equivalent:

<lang-ts>
    interface Props<T> {
        list: T[]
    }
</lang-ts>

<qk:spread #for={item of props.list}>
    <slot !item />
</qk:spread>

qingkuai has its own conventions: Props and Refs as reserved type names, <lang-ts> instead of <script>, slot context types auto-inferred from the slot tag — no manual declarations needed. An agent without access to these rules will always guess wrong on the details.

There's also the self-check problem. A generation loop that ends at "first output" will routinely hand you code that's almost right. The real chain is: generate → validate → fix → format. The MCP tools make that loop possible without manual review after every step.

---

The agent workflow with MCP

1. Look up syntax — before writing anything uncertain, call search_qingkuai_docs
2. Write the component — generate .qk following what was retrieved
3. Validate — call check_qingkuai_syntax immediately; fix any reported issues
4. Format — call format_qingkuai_code for consistent output

Steps that used to require your manual review get moved into the agent's own loop.

---

How to set it up

If you use the qingkuai VS Code extension, the MCP server is already built in — no configuration needed.

For standalone VS Code or external tools like Cursor and Claude Desktop, add the config manually:

VS Code (.vscode/mcp.json):

{
    "servers": {
        "qingkuai": {
            "command": "npx",
            "args": ["qingkuai-mcp-server"],
            "type": "stdio"
        }
    }
}

Claude Desktop (claude_desktop_config.json):

{
    "mcpServers": {
        "qingkuai": {
            "command": "npx",
            "args": ["qingkuai-mcp-server"]
        }
    }
}

---

Where this leaves you

MCP doesn't make the agent omniscient about qingkuai. More precisely: the agent moves from "mostly guessing" to "look up, write, verify." Syntax errors and missing validation are off the table. Component design, state architecture, and business logic — that's still on you.

But at least the syntax layer stops being a liability.

---

Want to try it?

• Online Playground — no install required
• Scaffold a project locally:

npm create qingkuai@latest my-app
cd my-app
npm install
npm run dev

• Docs · npm