@gwizai/sdk

A command-line interface for interacting with the Gwiz MCP service.

Installation

Using npx (Recommended)

No installation needed! Just run:

npx @gwizai/sdk --help

Global Installation

npm install -g @gwizai/sdk

Then use:

gwiz --help

Local Installation

npm install @gwizai/sdk

Then use via npx:

npx gwiz --help

Usage

Authentication

First, authenticate with the MCP service:

npx @gwizai/sdk auth login

This will open your browser to complete the OAuth flow. The authentication token will be saved to ~/.gwiz/config.json.

To log out:

npx @gwizai/sdk auth logout

Listing Tools

View all available MCP tools:

npx @gwizai/sdk tools list

Tool Commands

Search Emails

Search for emails using vector search:

npx @gwizai/sdk tools search-emails --query "meeting notes" --limit 10

With sender filter:

npx @gwizai/sdk tools search-emails --query "invoice" --from "[email protected]"

List Contacts

List all contacts:

npx @gwizai/sdk tools list-contacts

List Subscriptions

List all email subscriptions:

npx @gwizai/sdk tools list-subscriptions

Archive Emails

Archive one or more emails:

npx @gwizai/sdk tools archive --emailIds "msg1,msg2,msg3"

Create Draft

Create a draft email:

npx @gwizai/sdk tools draft --to "[email protected]" --subject "Hello" --body "Message body"

Or read body from a file:

npx @gwizai/sdk tools draft --to "[email protected]" --subject "Hello" --file message.txt

Reply to Email

Reply to an email:

npx @gwizai/sdk tools reply --emailId "msg123" --message "Thanks for your email!"

Or read reply from a file:

npx @gwizai/sdk tools reply --emailId "msg123" --file reply.txt

Unsubscribe

Unsubscribe from a subscription by email ID:

npx @gwizai/sdk tools unsubscribe --emailId "msg123"

Or by domain:

npx @gwizai/sdk tools unsubscribe --domain "example.com"

Publishing

To publish a new version to npm:

1. Update the version in package.json:

   npm version patch  # for 0.1.0 -> 0.1.1
   npm version minor  # for 0.1.0 -> 0.2.0
   npm version major  # for 0.1.0 -> 1.0.0

2. Build the package:

   cd apps/sdk
   bun run build

3. Publish to npm (make sure you're logged in to npm):

   npm publish --access public

   Note: Since this is a scoped package (@gwizai/sdk), you need to use --access public unless you have a paid npm account.

4. Verify the publication:

   npx @gwizai/sdk --help

Prerequisites for Publishing

1. npm account: Create an account at npmjs.com
2. Login to npm:

   npm login

3. Verify you're logged in:

   npm whoami

4. Ensure you have access to the @gwiz scope:
   • If the @gwiz organization doesn't exist, npm will create it when you publish
   • You may need to create the organization on npmjs.com first

Vercel AI SDK Integration

The package also exports a module for use with Vercel AI SDK's Agent:

import { gwiz } from "@gwizai/sdk/tools";
import { Agent } from "ai";

// Create tools with explicit configuration
const tools = await gwiz({
  url: "https://mcp.gwiz.ai",
  token: "your-token-here",
});

// Or use config file (from ~/.gwiz/config.json)
const tools = await gwiz();

// Use with Vercel AI SDK Agent
const agent = new Agent({
  // ... other configuration
  tools: {
    gmail: tools,
  },
});

The gwiz function returns an object where each key is an MCP tool name (e.g., search-emails, list-contacts, etc.) and each value is a Vercel AI SDK compatible tool.

Available Tools

When you call gwiz(), it dynamically loads all available MCP tools and converts them to Vercel AI SDK format. The tools include:

• search-emails - Search for emails using vector search
• list-contacts - List all contacts
• list-subscriptions - List email subscriptions
• archive - Archive emails
• draft - Create draft emails
• reply - Reply to emails
• unsubscribe - Unsubscribe from email subscriptions

Development

# Build
bun run build

# Run in development mode
bun run dev

# Type check
bun run typecheck

# Lint
bun run lint