@osiris-ai/cli/README.md

CLI for Osiris SDK - Create and manage MCP servers with authentication

# Osiris CLI

Build authenticated MCP servers with ease.

## What is Osiris CLI?

**Osiris CLI** is a command-line tool for creating and managing MCP (Model Context Protocol) servers with built-in authentication. Osiris stands for **"OAuth-Secured Intelligent Resource Integration System"** - a comprehensive platform for building AI-powered applications with secure authentication, policy enforcement, and blockchain integration.

**🔗 Links:**
- **Frontend**: [osirislabs.xyz](https://osirislabs.xyz)
- **API**: [api.osirislabs.xyz](https://api.osirislabs.xyz)
- **Discord**: [Join our community](https://discord.gg/v4prpEyw)

## 🚀 Quickstart

### Installation
Choose your preferred package manager:

```bash
# Using npm
npm install -g @osiris-ai/cli

# Using pnpm
pnpm add -g @osiris-ai/cli

# Using yarn
yarn global add @osiris-ai/cli

# Or use without installation
npx @osiris-ai/cli <command>
pnpm dlx @osiris-ai/cli <command>
yarn dlx @osiris-ai/cli <command>
```

### Getting Started (5 commands)

```bash
# 1. Register your account
npx @osiris-ai/cli register

# 2. Create OAuth client
npx @osiris-ai/cli create-client

# 3. Connect authentication services
npx @osiris-ai/cli connect-auth

# 4. Create your first MCP server
npx @osiris-ai/cli create-mcp

# 5. Start building! 🚀
cd your-project && npm run dev
```

## 📋 Commands

### Core Commands

#### `register`
Register a new user account with Osiris platform.
- Creates your Osiris account
- Sets up initial configuration
- Prepares your environment for OAuth client creation

#### `create-client` 
Create an OAuth client for your applications.
- Generates OAuth client credentials
- Configures authentication flows
- Required before creating MCP servers

#### `connect-auth`
Connect external authentication services to your account.
- Supports multiple OAuth providers
- Manages authentication tokens
- Enables service integrations for your MCP servers
- **New**: Enhanced wallet connection with Connection ID and Wallet ID display
- **New**: Simplified account listing with policy management

#### `create-mcp`
Create a new MCP server project with authentication.
- Generates complete project structure
- Installs dependencies automatically
- Configures authentication middleware
- Creates example tools, prompts, and resources
- **New**: User confirmation for publishing to Osiris Hub
- **New**: Enhanced package management with conditional publishing

**Generated Project Structure:**
```
my-mcp-project/
├── package.json
├── .env
├── .env.example
├── README.md
├── tsconfig.json (if TypeScript)
├── .gitignore
├── osiris.json
├── index.ts/js
├── client.ts/js
├── tools/
│   └── hello-world.ts/js
├── prompts/
│   └── hello-world.ts/js
├── resources/
│   └── hello-world.ts/js
└── schema/
    └── index.ts/js
```

**Osiris SDK Quickstart:**
```typescript
import { createMcpServer } from '@osiris-ai/sdk';
import { PostgresDatabaseAdapter } from '@osiris-ai/postgres-sdk';

await createMcpServer({
	name: "new-mcp",
	version: "1.0.0",
	auth: {
		useHub: true,
		hubConfig: {
			baseUrl: "https://api.osirislabs.xyz/v1",
			clientId: "osiris-client-id",
			clientSecret: "osiris-client-secret",
		},
		database: new PostgresDatabaseAdapter({
			connectionString: databaseUrl
		})
	},
	server: {
		port,
		mcpPath: "/mcp",
		callbackBasePath: "/callback",
		baseUrl: `http://localhost:${port}`,
		osirisConfigPath: "./osiris.json",
		logger: (msg: string) => logger.info(msg)
	},
	configure: (server) => {
		logger.info("⚙️ Configuring server tools...");
		server.tool("hello_world", "Simple greeting tool", {}, async () => {
			return {
				content: [{
					type: "text",
					text: "Hello World from Osiris MCP!"
				}]
			};
		});
		logger.info("✅ MCP configured successfully");
	}
});
```

### Management Commands

#### `list-auth`
List all connected authentication services.
- Shows connected providers
- Displays authentication status
- Includes scope information

#### `list-clients`
List all your registered OAuth clients.
- Shows client IDs and metadata
- Displays client status
- Manages client configurations
- Includes both hub and local clients

#### `list-connections`
List all your MCP server connections.
- Shows deployed MCP servers
- Displays connection status
- Manages active connections

#### `list-mcps`
List all your MCP projects.
- Shows project details
- Displays project status
- Quick project overview

#### `connect-mcp-auth`
Connect authentication to specific MCP deployments.
- Links auth services to MCP servers
- Configures service-specific authentication
- Manages deployment permissions
- **New**: Enhanced service client validation
- **New**: Policy template selection (Allow All, Strict Policy, Custom Policy)

#### `update-mcp-auth`
Update authentication configuration for existing MCP servers.
- **New**: Choose between "Refresh MCP Connection" or "MCP Connection Policy"
- **New**: Policy template selection with custom JSON support
- Update service scopes and refresh authentication tokens
- Enhanced error handling and user guidance

## 🔐 Authentication & Security

Osiris CLI supports multiple authentication providers through dedicated SDKs:


#### **Credential Sanitization**
- Automatic sanitization of sensitive data in API responses
- Secure storage and retrieval of user credentials
- Enhanced token refresh mechanisms with JWT ID (jti) for uniqueness

### Supported Services

#### **OAuth Providers**

##### **GitHub**
- **SDK**: [`@osiris-ai/github-sdk`](https://npmjs.com/package/@osiris-ai/github-sdk)
- **Scopes**: `repo`, `user`, `admin:org`, `gist`, `notifications`
- **Use Cases**: Repository management, issue tracking, pull requests

##### **Google Services**
- **SDK**: [`@osiris-ai/google-sdk`](https://npmjs.com/package/@osiris-ai/google-sdk)
- **Services**: Gmail, Google Drive, Calendar, Sheets
- **Scopes**: `email`, `profile`, `drive`, `calendar`, `spreadsheets`

##### **Discord**
- **SDK**: [`@osiris-ai/discord-sdk`](https://npmjs.com/package/@osiris-ai/discord-sdk)
- **Scopes**: `identify`, `email`, `guilds`, `guilds.join`
- **Use Cases**: Bot management, server automation, user management

##### **Linear**
- **SDK**: [`@osiris-ai/linear-sdk`](https://npmjs.com/package/@osiris-ai/linear-sdk)
- **Scopes**: `read`, `write`, `admin`
- **Use Cases**: Issue tracking, project management, team coordination

##### **Notion**
- **SDK**: [`@osiris-ai/notion-sdk`](https://npmjs.com/package/@osiris-ai/notion-sdk)
- **Scopes**: `read`, `update`, `insert`
- **Use Cases**: Knowledge management, database operations, content creation

##### **Slack**
- **SDK**: [`@osiris-ai/slack-sdk`](https://npmjs.com/package/@osiris-ai/slack-sdk)
- **Scopes**: `chat:write`, `channels:read`, `users:read`
- **Use Cases**: Team communication, workflow automation, notifications

### Database Adapters

#### **PostgreSQL**
- **SDK**: [`@osiris-ai/postgres-sdk`](https://npmjs.com/package/@osiris-ai/postgres-sdk)
- **Features**: Connection pooling, query building, migrations
- **Use Cases**: Relational data storage, complex queries

#### **MongoDB**
- **SDK**: [`@osiris-ai/mongodb-sdk`](https://npmjs.com/package/@osiris-ai/mongodb-sdk)
- **Features**: Document operations, aggregation, indexing
- **Use Cases**: NoSQL data storage, flexible schemas

#### **Redis**
- **SDK**: [`@osiris-ai/redis-sdk`](https://npmjs.com/package/@osiris-ai/redis-sdk)
- **Features**: Caching, session storage, pub/sub
- **Use Cases**: High-performance caching, real-time features

#### **SQLite**
- **SDK**: [`@osiris-ai/sqlite-sdk`](https://npmjs.com/package/@osiris-ai/sqlite-sdk)
- **Features**: Local database, file-based storage
- **Use Cases**: Development, local data storage, embedded applications

### Specialized Services

#### **Innertube Captions**
- **SDK**: [`@osiris-ai/innertube-captions-sdk`](https://npmjs.com/package/@osiris-ai/innertube-captions-sdk)
- **Features**: YouTube caption extraction, video processing
- **Use Cases**: Content analysis, video transcription, accessibility

## Core SDK

#### **Main SDK**
- **SDK**: [`@osiris-ai/sdk`](https://npmjs.com/package/@osiris-ai/sdk)
- **Features**: MCP server creation, authentication middleware, core utilities
- **Version**: Latest with enhanced security and blockchain integration
- **Use Cases**: Foundation for all MCP servers built with Osiris

## 📋 Requirements

- Node.js 18.0.0 or higher
- npm, pnpm, or yarn package manager

## Support

- **Documentation**: [osirislabs.xyz](https://osirislabs.xyz)
- **API Reference**: [api.osirislabs.xyz](https://api.osirislabs.xyz)
- **Discord Community**: [Join us](https://discord.gg/v4prpEyw)
- **Issues**: Report bugs in our GitHub repository
- **Policy Builder**: [policy-builder.osirislabs.xyz](https://policy-builder.osirislabs.xyz)

## 🎯 What's New in Latest Release

- ⭐ **Hyperliquid Integration**: High-performance DeFi trading
- 🔐 **Enhanced Security**: Google Cloud KMS encryption
- 🏛️ **Policy Engine**: Advanced transaction policy management
- 📦 **New Services**: Gmail, Drive, Calendar, Discord, Linear, Notion
- 🔧 **Improved CLI**: Better error handling and user experience
- 🌐 **Blockchain Support**: Enhanced Web3 and DeFi capabilities
- 📊 **Analytics**: Comprehensive usage tracking and insights

---

**Ready to build the future of AI automation?** 🚀

With Osiris CLI's enhanced security, blockchain integration, and comprehensive service support, you can create sophisticated MCP servers that are production-ready from day one!