Protocol Comparison Guide

mutation CreateUser($input: UserInput!) {
  createUser(input: $input) {
    name
    email
  }
}

{
  operation: "create_resource",
  params: {
    resource_type: "user",
    resource_id: "user-123",
    name: "Alice",
    email: "alice@example.com"
  }
}

{
  __schema {
    types { name }
    queryType { name }
  }
}

// List all operations
{ operation: "introspect", params: { query: "operations" } }

// Get specific operation details
{ operation: "introspect", params: { query: "operations", name: "create_resource" } }

// List available types
{ operation: "introspect", params: { query: "types" } }

mutation UpdateUser($id: ID!, $input: UpdateUserInput!) {
  updateUser(id: $id, input: $input) {
    name
  }
}

{
  operation: "update_resource",
  params: {
    resource_id: "user-123",
    input: {                    // Everything in 'input' gets deep-merged
      name: "Updated Name",
      settings: { theme: "dark" }
    }
  }
}

{
  operation: "list_resources",
  params: {
    resource_type: "user",
    fields: ["name", "description", "metadata.tags"]
  }
}
// Returns only requested fields, reducing response tokens

{
  operation: "get_resource",
  params: {
    resource_id: "user-123",
    fields: "minimal"  // Preset: returns only essential fields
  }
}

db.users.insertOne({
  name: "Alice",
  description: "A helpful assistant",
  settings: { theme: "light" }
})

{
  operation: "create_resource",
  params: {
    resource_type: "user",
    resource_id: "alice",
    description: "A helpful assistant",
    settings: { theme: "light" }
  }
}

db.users.find({
  tags: { $in: ["creative", "writing"] }
}).limit(10)

{
  operation: "search",
  params: {
    query: "creative writing",
    scope: "local",
    limit: 10
  }
}

db.users.updateOne(
  { name: "Alice" },
  { $set: {
    description: "Updated",
    "metadata.triggers": ["helper"]
  }}
)

{
  operation: "update_resource",
  params: {
    resource_id: "alice",
    input: {
      description: "Updated",
      metadata: {
        triggers: ["helper"]
      }
    }
  }
}

{
  "id": "123",
  "name": "Alice",
  "description": "A helpful assistant",
  "created_at": "2024-01-15T10:30:00Z"
}

// Request
{
  operation: "create_resource",
  params: {
    resource_type: "user",
    resource_id: "alice",
    description: "A helpful assistant",
    settings: { theme: "light" }
  }
}

// Response
{
  success: true,
  data: {
    name: "alice",
    type: "user",
    description: "A helpful assistant",
    // ... full resource data
  }
}

paths:
  /users:
    post:
      summary: Create a user
      parameters: [...]

// Discover all operations
{ operation: "introspect", params: { query: "operations" } }

// Get specific operation docs
{ operation: "introspect", params: { query: "operations", name: "create_resource" } }

// Returns:
{
  operation: {
    name: "create_resource",
    endpoint: "CREATE",
    mcpTool: "mcp_aql_create",
    description: "Create a new resource",
    parameters: [
      { name: "resource_id", type: "string", required: true, description: "Resource identifier" },
      // ...
    ],
    examples: [...]
  }
}

INSERT INTO users (name, description, settings)
VALUES ('alice', 'A helpful assistant', '{"theme": "light"}');

{
  operation: "create_resource",
  params: {
    resource_type: "user",
    resource_id: "alice",
    description: "A helpful assistant",
    settings: { theme: "light" }
  }
}

SELECT * FROM users WHERE name = 'alice';

{
  operation: "get_resource",
  params: {
    resource_type: "user",
    resource_id: "alice"
  }
}

UPDATE users
SET description = 'Updated description'
WHERE name = 'alice';

{
  operation: "update_resource",
  params: {
    resource_id: "alice",
    input: { description: "Updated description" }
  }
}

SELECT * FROM users
WHERE description LIKE '%creative%'
   OR settings LIKE '%creative%'
LIMIT 10;

{
  operation: "search",
  params: {
    query: "creative",
    scope: "local",
    type: "user",
    limit: 10
  }
}

// Tool: create_user
{
  name: "alice",
  description: "A helpful assistant",
  settings: { theme: "light" }
}

// Endpoint: mcp_aql_create
{
  operation: "create_resource",
  params: {
    resource_type: "user",
    resource_id: "alice",
    description: "A helpful assistant",
    settings: { theme: "light" }
  }
}

// Tool: list_users
{ page: 1, pageSize: 10 }

// Endpoint: mcp_aql_read
{
  operation: "list_resources",
  params: {
    resource_type: "user",
    first: 10
  }
}

// Step 1: Quick discovery (~50 tokens)
{ operation: "introspect", params: { query: "operations" } }

// Step 2: Get details for relevant operation (~100 tokens)
{ operation: "introspect", params: { query: "operations", name: "create_resource" } }

// Step 3: Use the operation
{ operation: "create_resource", ... }

mutation CreateUser($input: UserInput!) {
  createUser(input: $input) {
    id
    name
    email
  }
}

# Variables
{
  "input": {
    "name": "CreativeWriter",
    "email": "writer@example.com",
    "bio": "A creative writing assistant"
  }
}

db.users.insertOne({
  name: "CreativeWriter",
  email: "writer@example.com",
  bio: "A creative writing assistant",
  created_at: new Date()
});

INSERT INTO users (name, description, settings, created_at)
VALUES (
  'CreativeWriter',
  'A creative writing assistant',
  '{"expertise": "storytelling, poetry, imaginative content"}',
  NOW()
);

// Tool: create_user
{
  name: "CreativeWriter",
  description: "A creative writing assistant",
  settings: { expertise: "storytelling, poetry, imaginative content" }
}

// Endpoint: mcp_aql_create
{
  operation: "create_resource",
  params: {
    resource_type: "user",
    resource_id: "CreativeWriter",
    description: "A creative writing assistant",
    settings: { expertise: "storytelling, poetry, imaginative content" }
  }
}

query SearchUsers($query: String!, $limit: Int) {
  searchUsers(query: $query, limit: $limit) {
    results {
      name
      description
    }
    total
  }
}

# Variables
{ "query": "creative writing", "limit": 10 }

db.users.find({
  $text: { $search: "creative writing" }
}).limit(10).toArray();

SELECT * FROM users
WHERE description LIKE '%creative%'
   OR description LIKE '%writing%'
LIMIT 10;

// Tool: search_users
{
  query: "creative writing",
  type: "user",
  limit: 10
}

// Endpoint: mcp_aql_read
{
  operation: "search",
  params: {
    query: "creative writing",
    type: "user",
    scope: "local",
    limit: 10
  }
}

mutation UpdateUser($name: String!, $input: UpdateUserInput!) {
  updateUser(name: $name, input: $input) {
    name
    description
  }
}

# Variables
{
  "name": "CreativeWriter",
  "input": {
    "description": "An enhanced creative writing assistant with poetry expertise"
  }
}

db.users.updateOne(
  { name: "CreativeWriter" },
  { $set: { description: "An enhanced creative writing assistant with poetry expertise" } }
);

UPDATE users
SET description = 'An enhanced creative writing assistant with poetry expertise'
WHERE name = 'CreativeWriter';

// Tool: edit_user
{
  name: "CreativeWriter",
  description: "An enhanced creative writing assistant with poetry expertise"
}

// Endpoint: mcp_aql_update
{
  operation: "update_resource",
  params: {
    resource_id: "CreativeWriter",
    input: {
      description: "An enhanced creative writing assistant with poetry expertise"
    }
  }
}

{
  __schema {
    mutationType {
      fields {
        name
        description
      }
    }
  }
}

// No direct equivalent - typically use documentation
db.getCollectionInfos();

SHOW TABLES;
DESCRIBE users;

// Endpoint: mcp_aql_read
// List all operations
{ operation: "introspect", params: { query: "operations" } }

// Get details for specific operation
{ operation: "introspect", params: { query: "operations", name: "update_resource" } }

// List available types
{ operation: "introspect", params: { query: "types" } }