@affectively/mcp-framework

A framework for building Model Context Protocol (MCP) servers with built-in authentication, tool registration, and analytics.

What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI applications to securely connect with data sources and tools. This framework makes it easy to build MCP servers that integrate with:

• GitHub Copilot
• Claude Desktop
• Cursor
• Other MCP-compatible clients

Features

• Tool Registration - Declarative tool definition with JSON Schema validation
• Authentication - Firebase Auth integration with token management
• Transport Modes - stdio (local) and HTTP (deployed) support
• Analytics - Optional GA4 Measurement Protocol integration
• Type Safety - Full TypeScript support with inference

Installation

npm install @affectively/mcp-framework
# or
yarn add @affectively/mcp-framework
# or
bun add @affectively/mcp-framework

Quick Start

import { createMCPServer, defineTool } from '@affectively/mcp-framework';

// Define a tool
const greetTool = defineTool({
 name: 'greet',
 description: 'Greet a user by name',
 inputSchema: {
 type: 'object',
 properties: {
 name: { type: 'string', description: 'Name to greet' }
 },
 required: ['name']
 },
 handler: async ({ name }) => {
 return { content: [{ type: 'text', text: `Hello, ${name}!` }] };
 }
});

// Create and start server
const server = createMCPServer({
 name: 'my-mcp-server',
 version: '1.0.0',
 tools: [greetTool]
});

server.start();

Configuration

Environment Variables

# Transport mode: 'stdio' (default) or 'http'
TRANSPORT_MODE=stdio

# HTTP mode settings
PORT=3001
CORS_ORIGIN=*

# Authentication (optional)
FIREBASE_AUTH_TOKEN=your-token-here

# Analytics (optional)
GA4_MEASUREMENT_ID=G-XXXXXXXXXX
GA4_API_SECRET=your-api-secret

MCP Client Configuration

Add to your MCP client config (e.g., ~/.cursor/mcp.json):

{
 "mcpServers": {
 "my-server": {
 "command": "npx",
 "args": ["-y", "@affectively/mcp-framework"],
 "env": {
 "API_BASE_URL": "https://api.example.com"
 }
 }
 }
}

Tool Definition

import { defineTool } from '@affectively/mcp-framework';

const myTool = defineTool({
 // Required
 name: 'tool_name',
 description: 'What this tool does',
 inputSchema: {
 type: 'object',
 properties: {
 param1: { type: 'string', description: 'Description' }
 },
 required: ['param1']
 },
 handler: async (input, context) => {
 // context includes: authToken, userId, logger
 return {
 content: [{ type: 'text', text: 'Result' }]
 };
 },
 
 // Optional
 requiresAuth: true,
 subscriptionTier: 'premium', // 'free' | 'premium' | 'enterprise'
});

Authentication

Token File Authentication

The framework supports token file authentication for persistent sessions:

import { createMCPServer, withAuth } from '@affectively/mcp-framework';

const server = createMCPServer({
 name: 'my-server',
 version: '1.0.0',
 tools: [myTool],
 auth: {
 tokenFilePath: '~/.mcp-auth-token',
 refreshEndpoint: 'https://api.example.com/token/refresh'
 }
});

Built-in Auth Tools

The framework includes built-in tools for authentication:

• check_login_state - Check current auth status
• get_login_url - Generate browser login URL
• login_with_token - Save token from browser flow

HTTP Mode

For deployed servers, enable HTTP transport:

const server = createMCPServer({
 name: 'my-server',
 version: '1.0.0',
 tools: [myTool],
 transport: {
 mode: 'http',
 port: 3001,
 cors: true
 }
});

Analytics

Track tool usage with GA4:

const server = createMCPServer({
 name: 'my-server',
 version: '1.0.0',
 tools: [myTool],
 analytics: {
 measurementId: 'G-XXXXXXXXXX',
 apiSecret: 'your-secret'
 }
});

Tracked events:

• mcp_tool_call - When a tool is invoked
• mcp_tool_complete - When a tool completes successfully
• mcp_tool_error - When a tool fails

API Reference

createMCPServer(options)

Create a new MCP server instance.

defineTool(config)

Define a tool with type-safe input/output.

withAuth(handler)

Wrap a handler to require authentication.

withSubscription(tier, handler)

Wrap a handler to require a subscription tier.

Examples

See the examples/ directory for:

• Basic tool server
• Authenticated API proxy
• Multi-tool server with analytics

Related Packages

• @affectively/behavioral-taxonomy - Emotion datasets
• @affectively/utils - Utility functions

License

MIT License - see LICENSE for details.

---

Made with ️ by AFFECTIVELY