Add agent-native MCP layer and tinybench benchmarks

Author: dev-dami

README.MD

@@ -103,6 +103,30 @@ This repository includes GitHub Actions workflows:
 - `ci.yml`: runs install, build, tests, and coverage on push/PR.
 - `release.yml`: runs release checks and can publish to npm on version tags (`v*`) when `NPM_TOKEN` is configured.
 
+## Agent-Native Mode
+
+Qirrel ships with an agent-native bridge plus an MCP server so the same parsing core works for API code and agent toolchains.
+
+```ts
+import { createQirrelAgentBridge } from "qirrel";
+
+const bridge = createQirrelAgentBridge();
+const result = await bridge.callTool("qirrel.parse_text", { text: "Email me@example.com" });
+console.log(result.structuredContent);
+```
+
+Run MCP server:
+
+```bash
+bun run mcp:start
+```
+
+Run benchmark:
+
+```bash
+bun run bench:agent
+```
+
 ## Documentation
 
 - [Docs Home](./docs/README.md)
@@ -114,6 +138,7 @@ This repository includes GitHub Actions workflows:
 - [Pipeline Events](./docs/events.md)
 - [LLM Integration](./docs/integrations/llm.md)
 - [Architecture Walkthrough](./docs/walkthrough.md)
+- [Agent-Native Integration](./docs/agent-native.md)
 
 ## Contributing
 

bench/agent-native.bench.ts

@@ -0,0 +1,45 @@
+import { Bench } from "tinybench";
+import { processText } from "../src/api";
+import { createMcpRequestHandler, createQirrelAgentBridge } from "../src/agent";
+
+const sampleText =
+  "Contact support@example.com or +1 415 555 2671 and visit https://example.com";
+
+async function run(): Promise<void> {
+  const bridge = createQirrelAgentBridge();
+  const handle = createMcpRequestHandler(bridge);
+  const bench = new Bench({ time: 1_000, warmupTime: 300 });
+
+  bench.add("direct: processText()", async () => {
+    await processText(sampleText);
+  });
+
+  bench.add("agent bridge: qirrel.parse_text", async () => {
+    await bridge.callTool("qirrel.parse_text", { text: sampleText });
+  });
+
+  bench.add("mcp handler: tools/call", async () => {
+    await handle({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "tools/call",
+      params: {
+        name: "qirrel.parse_text",
+        arguments: { text: sampleText },
+      },
+    });
+  });
+
+  await bench.run();
+
+  const rows = bench.tasks.map((task) => ({
+    name: task.name,
+    "ops/sec": task.result ? Math.round(task.result.hz) : 0,
+    "avg ms": task.result ? Number(task.result.mean.toFixed(3)) : 0,
+    "p99 ms": task.result ? Number(task.result.p99.toFixed(3)) : 0,
+  }));
+
+  console.table(rows);
+}
+
+void run();

bun.lock

@@ -13,9 +13,10 @@ GitHub-first Markdown docs for Qirrel.
 - [Pipeline Events](./events.md)
 - [LLM Integration](./integrations/llm.md)
 - [Architecture Walkthrough](./walkthrough.md)
+- [Agent-Native Integration](./agent-native.md)
 
 ## Quick Navigation
 
 - Core: [API](./api.md) | [Configuration](./configuration.md) | [Examples](./examples.md)
 - Usage: [Basic](./usage/basic.md) | [Caching](./usage/caching.md)
-- Advanced: [Events](./events.md) | [LLM](./integrations/llm.md) | [Architecture](./walkthrough.md)
+- Advanced: [Events](./events.md) | [LLM](./integrations/llm.md) | [Architecture](./walkthrough.md) | [Agent-Native](./agent-native.md)

docs/README.md

@@ -0,0 +1,82 @@
+# Agent-Native Integration
+
+[Docs Home](./README.md) | [API](./api.md) | [Configuration](./configuration.md) | [Examples](./examples.md) | [Basic](./usage/basic.md) | [Caching](./usage/caching.md) | [Events](./events.md) | [LLM](./integrations/llm.md) | [Architecture](./walkthrough.md)
+
+Qirrel now includes an agent-native layer with:
+
+- a reusable `AgentBridge` abstraction
+- built-in Qirrel tools (`qirrel.parse_text`, `qirrel.parse_batch`)
+- a lightweight MCP JSON-RPC server (`qirrel-mcp`)
+- tinybench benchmarks for direct vs agent-mode overhead
+
+## Core Idea
+
+Use one structure for both classic API calls and agent tools:
+
+- Regular function: `processText(text)`
+- Agent tool: `qirrel.parse_text({ text })`
+
+`AgentBridge.registerApiTool(...)` adapts non-agent-native handlers into MCP-style tool results with both:
+
+- `content` (agent-readable text)
+- `structuredContent` (machine-usable JSON)
+
+## Use the Built-In Bridge
+
+```ts
+import { createQirrelAgentBridge } from "qirrel";
+
+const bridge = createQirrelAgentBridge();
+const result = await bridge.callTool("qirrel.parse_text", {
+  text: "Email hello@example.com",
+});
+
+console.log(result.structuredContent);
+```
+
+## Wrap Your Existing APIs
+
+```ts
+import { AgentBridge } from "qirrel";
+
+const bridge = new AgentBridge();
+
+bridge.registerApiTool(
+  {
+    name: "inventory.lookup",
+    description: "Lookup stock by SKU",
+    inputSchema: {
+      type: "object",
+      properties: { sku: { type: "string" } },
+      required: ["sku"],
+    },
+  },
+  async ({ sku }: { sku: string }) => {
+    return { sku, inStock: true };
+  },
+);
+```
+
+## Start MCP Server (stdio)
+
+```bash
+bun run mcp:start
+```
+
+Or after install:
+
+```bash
+qirrel-mcp
+```
+
+## Benchmark Agent Overhead
+
+```bash
+bun run bench:agent
+```
+
+This compares:
+
+- direct API (`processText`)
+- tool call via `AgentBridge`
+- MCP `tools/call` request handler path

docs/agent-native.md

@@ -1,6 +1,6 @@
 # API Reference
 
-[Docs Home](./README.md) | [Configuration](./configuration.md) | [Examples](./examples.md) | [Basic](./usage/basic.md) | [Caching](./usage/caching.md) | [Events](./events.md) | [LLM](./integrations/llm.md) | [Architecture](./walkthrough.md)
+[Docs Home](./README.md) | [Configuration](./configuration.md) | [Examples](./examples.md) | [Basic](./usage/basic.md) | [Caching](./usage/caching.md) | [Events](./events.md) | [LLM](./integrations/llm.md) | [Architecture](./walkthrough.md) | [Agent-Native](./agent-native.md)
 
 ## Top-Level Functions
 

docs/api.md

@@ -1,6 +1,6 @@
 # Configuration Guide
 
-[Docs Home](./README.md) | [API](./api.md) | [Examples](./examples.md) | [Basic](./usage/basic.md) | [Caching](./usage/caching.md) | [Events](./events.md) | [LLM](./integrations/llm.md) | [Architecture](./walkthrough.md)
+[Docs Home](./README.md) | [API](./api.md) | [Examples](./examples.md) | [Basic](./usage/basic.md) | [Caching](./usage/caching.md) | [Events](./events.md) | [LLM](./integrations/llm.md) | [Architecture](./walkthrough.md) | [Agent-Native](./agent-native.md)
 
 Qirrel loads config in this order:
 

docs/configuration.md

@@ -1,6 +1,6 @@
 # Pipeline Events
 
-[Docs Home](./README.md) | [API](./api.md) | [Configuration](./configuration.md) | [Examples](./examples.md) | [Basic](./usage/basic.md) | [Caching](./usage/caching.md) | [LLM](./integrations/llm.md) | [Architecture](./walkthrough.md)
+[Docs Home](./README.md) | [API](./api.md) | [Configuration](./configuration.md) | [Examples](./examples.md) | [Basic](./usage/basic.md) | [Caching](./usage/caching.md) | [LLM](./integrations/llm.md) | [Architecture](./walkthrough.md) | [Agent-Native](./agent-native.md)
 
 Qirrel exposes lifecycle events on `Pipeline` so you can monitor execution, collect metrics, and handle failures without modifying core processors.
 

docs/events.md

@@ -1,6 +1,6 @@
 # Usage Examples
 
-[Docs Home](./README.md) | [API](./api.md) | [Configuration](./configuration.md) | [Basic](./usage/basic.md) | [Caching](./usage/caching.md) | [Events](./events.md) | [LLM](./integrations/llm.md) | [Architecture](./walkthrough.md)
+[Docs Home](./README.md) | [API](./api.md) | [Configuration](./configuration.md) | [Basic](./usage/basic.md) | [Caching](./usage/caching.md) | [Events](./events.md) | [LLM](./integrations/llm.md) | [Architecture](./walkthrough.md) | [Agent-Native](./agent-native.md)
 
 ## Single Input
 

docs/examples.md

@@ -1,6 +1,6 @@
 # LLM Integration
 
-[Docs Home](../README.md) | [API](../api.md) | [Configuration](../configuration.md) | [Examples](../examples.md) | [Basic](../usage/basic.md) | [Caching](../usage/caching.md) | [Events](../events.md) | [Architecture](../walkthrough.md)
+[Docs Home](../README.md) | [API](../api.md) | [Configuration](../configuration.md) | [Examples](../examples.md) | [Basic](../usage/basic.md) | [Caching](../usage/caching.md) | [Events](../events.md) | [Architecture](../walkthrough.md) | [Agent-Native](../agent-native.md)
 
 Qirrel supports pluggable LLM adapters (`gemini`, `openai`, and generic OpenAI-compatible endpoints).