{"_id":"@affectively/mcp-framework","_rev":"4-78005121b22d4d56c45e2d7c267d164e","name":"@affectively/mcp-framework","dist-tags":{"latest":"5.0.1"},"versions":{"1.0.0":{"name":"@affectively/mcp-framework","version":"1.0.0","keywords":["mcp","model-context-protocol","ai-agents","github-copilot","claude","tool-server","authentication","firebase"],"author":{"name":"AFFECTIVELY","email":"opensource@affectively.app"},"license":"MIT","_id":"@affectively/mcp-framework@1.0.0","maintainers":[{"name":"buley","email":"buley@outlook.com"}],"homepage":"https://github.com/affectively-ai/mcp-framework#readme","bugs":{"url":"https://github.com/affectively-ai/mcp-framework/issues"},"bin":{"mcp-server":"dist/cli.js"},"dist":{"shasum":"ad21d422b8d474c87d6b72b9028f5389ad608bca","tarball":"https://registry.npmjs.org/@affectively/mcp-framework/-/mcp-framework-1.0.0.tgz","fileCount":13,"integrity":"sha512-7fhAvy6pHZtBo1TQtPuntJC9HMgY3sQWW7AoFovdEeO2nx3Iblysm0zybwjE0RKHd8L2C0IEyfgarCLIznlU+Q==","signatures":[{"sig":"MEUCIQCl9hvDFomtQjTZvU9AlabtKvL5HFRpScpm4PPTT286OQIgbSvITHG2AZoZXnmECOqEFZvQMgB9+Os/8jQ90n8n/jE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":39719},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"e00808eb0206312f7690bffd7e2fc1cc8b35b1bb","scripts":{"dev":"bun run src/cli.ts","test":"bun test","build":"tsup src/index.ts src/cli.ts --format cjs,esm --dts","start":"node dist/cli.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"buley","email":"buley@outlook.com"},"repository":{"url":"git+https://github.com/affectively-ai/mcp-framework.git","type":"git"},"_npmVersion":"11.6.2","description":"Framework for building Model Context Protocol (MCP) servers with authentication, tool registration, and analytics.","directories":{},"_nodeVersion":"24.11.1","dependencies":{"cors":"^2.8.5","express":"^5.0.0","@modelcontextprotocol/sdk":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","typescript":"^5.9.0","@types/cors":"^2.8.0","@types/express":"^5.0.0"},"peerDependencies":{"firebase":">=10.0.0"},"peerDependenciesMeta":{"firebase":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/mcp-framework_1.0.0_1768339372198_0.5125877263226648","host":"s3://npm-registry-packages-npm-production"},"deprecated":"This package is deprecated and no longer supported. Do not use."},"1.0.1":{"name":"@affectively/mcp-framework","version":"1.0.1","keywords":["mcp","model-context-protocol","ai-agents","github-copilot","claude","tool-server","authentication","firebase"],"author":{"name":"AFFECTIVELY","email":"opensource@affectively.ai"},"license":"MIT","_id":"@affectively/mcp-framework@1.0.1","maintainers":[{"name":"buley","email":"buley@outlook.com"}],"homepage":"https://github.com/affectively-ai/mcp-framework#readme","bugs":{"url":"https://github.com/affectively-ai/mcp-framework/issues"},"bin":{"mcp-server":"dist/cli.js"},"dist":{"shasum":"ed3ce577f351acc6666af2a17f298cd527bd474a","tarball":"https://registry.npmjs.org/@affectively/mcp-framework/-/mcp-framework-1.0.1.tgz","fileCount":13,"integrity":"sha512-m+e3J1fW8lyF0Ws3OQKYv58noiUmBU4qkYtETVMkNvyJeGXdrjMilwUt659R03SjscdHYurSNgjz8IU4t+WsXQ==","signatures":[{"sig":"MEYCIQD9aUHprReSBNkwEikoJu2PLXSHtNLS4kMWJoX7rU59XAIhALjuH4aLX2FkSR7+7FDtX3zqTkJarbpytCUIhTH4RgKv","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":39574},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"9d6a062bd357886982780d418d5922678263c44c","scripts":{"dev":"bun run src/cli.ts","test":"bun test","build":"tsup src/index.ts src/cli.ts --format cjs,esm --dts","start":"node dist/cli.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"buley","email":"buley@outlook.com"},"repository":{"url":"git+https://github.com/affectively-ai/mcp-framework.git","type":"git"},"_npmVersion":"11.6.2","description":"Framework for building Model Context Protocol (MCP) servers with authentication, tool registration, and analytics.","directories":{},"_nodeVersion":"24.11.1","dependencies":{"cors":"^2.8.5","express":"^5.0.0","@modelcontextprotocol/sdk":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","typescript":"^5.9.0","@types/cors":"^2.8.0","@types/express":"^5.0.0"},"peerDependencies":{"firebase":">=10.0.0"},"peerDependenciesMeta":{"firebase":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/mcp-framework_1.0.1_1768341113157_0.8094184891765615","host":"s3://npm-registry-packages-npm-production"},"deprecated":"This package is deprecated and no longer supported. Do not use."},"5.0.1":{"name":"@affectively/mcp-framework","version":"5.0.1","keywords":["mcp","model-context-protocol","ai-agents","github-copilot","claude","tool-server","authentication","firebase"],"author":{"url":"https://buley.fyi","name":"Taylor William Buley"},"license":"UNLICENSED","_id":"@affectively/mcp-framework@5.0.1","maintainers":[{"name":"buley","email":"buley@outlook.com"}],"homepage":"https://github.com/affectively-ai/mcp-framework#readme","bugs":{"url":"https://github.com/affectively-ai/mcp-framework/issues"},"bin":{"mcp-server":"dist/cli.js"},"dist":{"shasum":"eaa6f66add1bca8563ef9499d4548f0697e391ad","tarball":"https://registry.npmjs.org/@affectively/mcp-framework/-/mcp-framework-5.0.1.tgz","fileCount":8,"integrity":"sha512-SoEJSgYOdhrAxa6hFkQl27gLDpKP1cNbiKnpJ45gcOIujnooLChoCdpLmm9GIjzWjPMIgmCktpo5bgljr6YeQQ==","signatures":[{"sig":"MEYCIQCpaAFEIfA/6jW31/5LgeMCTgPIh+tFj2IguALqES7YwwIhAKnrDkqFq/f5OQqBYKCx7/oWmwScb3g/s4F003onYI1d","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":45325},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"dev":"bun run src/cli.ts","test":"bun test","build":"tsup src/index.ts src/cli.ts --format cjs,esm --dts","start":"node dist/cli.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"buley","email":"buley@outlook.com"},"repository":{"url":"git+https://github.com/affectively-ai/mcp-framework.git","type":"git"},"_npmVersion":"11.8.0","description":"Framework for building Model Context Protocol (MCP) servers with authentication, tool registration, and analytics.","directories":{},"_nodeVersion":"25.5.0","dependencies":{"cors":"^2.8.5","express":"^5.0.0","@modelcontextprotocol/sdk":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","typescript":"^5.9.0","@types/cors":"^2.8.0","@types/node":"^25.3.2","@types/express":"^5.0.0"},"peerDependencies":{"firebase":">=10.0.0"},"peerDependenciesMeta":{"firebase":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/mcp-framework_5.0.1_1773157485753_0.40222762998869865","host":"s3://npm-registry-packages-npm-production"},"deprecated":"This package is deprecated and no longer supported. Do not use."}},"time":{"created":"2026-01-13T21:22:52.137Z","modified":"2026-03-27T20:03:36.934Z","1.0.0":"2026-01-13T21:22:52.335Z","1.0.1":"2026-01-13T21:51:53.310Z","5.0.1":"2026-03-10T15:44:46.022Z"},"bugs":{"url":"https://github.com/affectively-ai/mcp-framework/issues"},"author":{"url":"https://buley.fyi","name":"Taylor William Buley"},"license":"UNLICENSED","homepage":"https://github.com/affectively-ai/mcp-framework#readme","keywords":["mcp","model-context-protocol","ai-agents","github-copilot","claude","tool-server","authentication","firebase"],"repository":{"url":"git+https://github.com/affectively-ai/mcp-framework.git","type":"git"},"description":"Framework for building Model Context Protocol (MCP) servers with authentication, tool registration, and analytics.","maintainers":[{"name":"buley","email":"buley@outlook.com"}],"readme":"# @affectively/mcp-framework\r\n\r\nA framework for building **Model Context Protocol (MCP)** servers with built-in authentication, tool registration, and analytics.\r\n\r\n[![npm version](https://img.shields.io/npm/v/@affectively/mcp-framework.svg)](https://www.npmjs.com/package/@affectively/mcp-framework)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\r\n\r\n## What is MCP?\r\n\r\nThe [Model Context Protocol (MCP)](https://www.anthropic.com/news/model-context-protocol) 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:\r\n\r\n- **GitHub Copilot**\r\n- **Claude Desktop**\r\n- **Cursor**\r\n- **Other MCP-compatible clients**\r\n\r\n## Features\r\n\r\n- **Tool Registration** - Declarative tool definition with JSON Schema validation\r\n- **Authentication** - Firebase Auth integration with token management\r\n- **Transport Modes** - stdio (local) and HTTP (deployed) support\r\n- **Analytics** - Optional GA4 Measurement Protocol integration\r\n- **Type Safety** - Full TypeScript support with inference\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @affectively/mcp-framework\r\n# or\r\nyarn add @affectively/mcp-framework\r\n# or\r\nbun add @affectively/mcp-framework\r\n```\r\n\r\n## Quick Start\n\n```typescript\nimport { createMCPServer, defineTool } from '@affectively/mcp-framework';\n\r\n// Define a tool\r\nconst greetTool = defineTool({\r\n name: 'greet',\r\n description: 'Greet a user by name',\r\n inputSchema: {\r\n type: 'object',\r\n properties: {\r\n name: { type: 'string', description: 'Name to greet' }\r\n },\r\n required: ['name']\r\n },\r\n handler: async ({ name }) => {\r\n return { content: [{ type: 'text', text: `Hello, ${name}!` }] };\r\n }\r\n});\r\n\r\n// Create and start server\r\nconst server = createMCPServer({\r\n name: 'my-mcp-server',\r\n version: '1.0.0',\r\n tools: [greetTool]\r\n});\r\n\r\nserver.start();\n```\n\n## Fractal Canonical Tool Packs\n\nUse the built-in canonical Fractal packs (`todo_*`, `fact_*`, `memory_*`) as the primary tool surface.\n\n```typescript\nimport {\n  createMCPServer,\n  createFractalTodoToolPack,\n  createFractalFactToolPack,\n  createFractalMemoryToolPack,\n} from '@affectively/mcp-framework';\n\nconst server = createMCPServer({\n  name: 'fractal-canonical-server',\n  version: '1.0.0',\n  tools: [\n    ...createFractalTodoToolPack({ endpoint: 'https://task.yoga/mcp' }),\n    ...createFractalFactToolPack({ endpoint: 'https://fact.guide/mcp' }),\n    ...createFractalMemoryToolPack({ endpoint: 'https://memo.yoga/mcp' }),\n  ],\n});\n\nserver.start();\n```\n\nOptional auth forwarding:\n\n```typescript\nconst todoPack = createFractalTodoToolPack({\n  authTokenResolver: async (context) => context.authToken ?? null,\n});\n```\n\r\n## Configuration\r\n\r\n### Environment Variables\r\n\r\n```bash\r\n# Transport mode: 'stdio' (default) or 'http'\r\nTRANSPORT_MODE=stdio\r\n\r\n# HTTP mode settings\r\nPORT=3001\r\nCORS_ORIGIN=*\r\n\r\n# Authentication (optional)\r\nFIREBASE_AUTH_TOKEN=your-token-here\r\n\r\n# Analytics (optional)\r\nGA4_MEASUREMENT_ID=G-XXXXXXXXXX\r\nGA4_API_SECRET=your-api-secret\r\n```\r\n\r\n### MCP Client Configuration\r\n\r\nAdd to your MCP client config (e.g., `~/.cursor/mcp.json`):\r\n\r\n```json\r\n{\r\n \"mcpServers\": {\r\n \"my-server\": {\r\n \"command\": \"npx\",\r\n \"args\": [\"-y\", \"@affectively/mcp-framework\"],\r\n \"env\": {\r\n \"API_BASE_URL\": \"https://api.example.com\"\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\n## Tool Definition\r\n\r\n```typescript\r\nimport { defineTool } from '@affectively/mcp-framework';\r\n\r\nconst myTool = defineTool({\r\n // Required\r\n name: 'tool_name',\r\n description: 'What this tool does',\r\n inputSchema: {\r\n type: 'object',\r\n properties: {\r\n param1: { type: 'string', description: 'Description' }\r\n },\r\n required: ['param1']\r\n },\r\n handler: async (input, context) => {\r\n // context includes: authToken, userId, logger\r\n return {\r\n content: [{ type: 'text', text: 'Result' }]\r\n };\r\n },\r\n \r\n // Optional\r\n requiresAuth: true,\r\n subscriptionTier: 'premium', // 'free' | 'premium' | 'enterprise'\r\n});\r\n```\r\n\r\n## Authentication\r\n\r\n### Token File Authentication\r\n\r\nThe framework supports token file authentication for persistent sessions:\r\n\r\n```typescript\r\nimport { createMCPServer, withAuth } from '@affectively/mcp-framework';\r\n\r\nconst server = createMCPServer({\r\n name: 'my-server',\r\n version: '1.0.0',\r\n tools: [myTool],\r\n auth: {\r\n tokenFilePath: '~/.mcp-auth-token',\r\n refreshEndpoint: 'https://api.example.com/token/refresh'\r\n }\r\n});\r\n```\r\n\r\n### Built-in Auth Tools\r\n\r\nThe framework includes built-in tools for authentication:\r\n\r\n- `check_login_state` - Check current auth status\r\n- `get_login_url` - Generate browser login URL\r\n- `login_with_token` - Save token from browser flow\r\n\r\n## HTTP Mode\r\n\r\nFor deployed servers, enable HTTP transport:\r\n\r\n```typescript\r\nconst server = createMCPServer({\r\n name: 'my-server',\r\n version: '1.0.0',\r\n tools: [myTool],\r\n transport: {\r\n mode: 'http',\r\n port: 3001,\r\n cors: true\r\n }\r\n});\r\n```\r\n\r\n## Analytics\r\n\r\nTrack tool usage with GA4:\r\n\r\n```typescript\r\nconst server = createMCPServer({\r\n name: 'my-server',\r\n version: '1.0.0',\r\n tools: [myTool],\r\n analytics: {\r\n measurementId: 'G-XXXXXXXXXX',\r\n apiSecret: 'your-secret'\r\n }\r\n});\r\n```\r\n\r\nTracked events:\r\n- `mcp_tool_call` - When a tool is invoked\r\n- `mcp_tool_complete` - When a tool completes successfully\r\n- `mcp_tool_error` - When a tool fails\r\n\r\n## API Reference\r\n\r\n### `createMCPServer(options)`\r\n\r\nCreate a new MCP server instance.\r\n\r\n### `defineTool(config)`\r\n\r\nDefine a tool with type-safe input/output.\r\n\r\n### `withAuth(handler)`\r\n\r\nWrap a handler to require authentication.\r\n\r\n### `withSubscription(tier, handler)`\r\n\r\nWrap a handler to require a subscription tier.\r\n\r\n## Examples\r\n\r\nSee the [examples/](./examples/) directory for:\r\n\r\n- Basic tool server\r\n- Authenticated API proxy\r\n- Multi-tool server with analytics\r\n\r\n## Related Packages\r\n\r\n- [`@affectively/behavioral-taxonomy`](https://www.npmjs.com/package/@affectively/behavioral-taxonomy) - Emotion datasets\r\n- [`@affectively/utils`](https://www.npmjs.com/package/@affectively/utils) - Utility functions\r\n\r\n## License\r\n\r\nMIT License - see [LICENSE](./LICENSE) for details.\r\n\r\n---\r\n\r\nMade with ️ by [AFFECTIVELY](https://affectively.ai)\r\n","readmeFilename":"README.md"}