@prmichaelsen/task-mcp 0.2.0

package/agent/tasks/task-89-mcp-server-implementation.md

@@ -0,0 +1,197 @@
+# Task 90: MCP Server Implementation
+
+**Milestone**: Milestone 2 - MCP Server Foundation
+**Estimated Time**: 8 hours
+**Dependencies**: Task 89 (Core MCP Tools)
+**Status**: Not Started
+
+---
+
+## Objective
+
+Create the MCP server implementation that exposes task management tools via MCP protocol. Implement both standalone server (stdio transport) and server factory (multi-tenant) following the MCP Server Bootstrap Pattern.
+
+## Steps
+
+### 1. Install MCP SDK
+
+Install dependencies:
+```bash
+npm install @modelcontextprotocol/sdk
+```
+
+### 2. Create Server Factory
+
+Create `src/server-factory.ts`:
+- Export `createServer(userId, options)` function
+- Initialize FirebaseClient with userId
+- Create MCP Server instance
+- Register all tools from `src/tools/`
+- Handle `list_tools` requests
+- Handle `call_tool` requests
+- Return configured Server instance
+
+### 3. Create Standalone Server
+
+Create `src/server.ts`:
+- CLI entry point for stdio transport
+- Load userId from environment or args
+- Use server factory to create instance
+- Connect with StdioServerTransport
+- Handle graceful shutdown
+
+### 4. Create CLI Entry Point
+
+Create `src/index.ts`:
+- Parse command line arguments
+- Load environment variables
+- Start standalone server
+- Handle errors
+
+### 5. Create Types
+
+Create `src/types.ts`:
+- MCP-specific type definitions
+- Server options interface
+- Tool handler types
+- Export shared types
+
+### 6. Write Unit Tests
+
+Create tests:
+- `src/server-factory.spec.ts` - Test factory function
+- `src/server.spec.ts` - Test server initialization
+- Test tool registration
+- Test request handling
+
+## Verification
+
+- [ ] Server factory creates isolated instances
+- [ ] Standalone server starts with stdio
+- [ ] All tools registered correctly
+- [ ] list_tools returns all 8 tools
+- [ ] call_tool executes tools correctly
+- [ ] Error handling works
+- [ ] Unit tests pass
+- [ ] TypeScript compiles without errors
+
+## Example Server Factory
+
+```typescript
+// src/server-factory.ts
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ErrorCode,
+  McpError
+} from '@modelcontextprotocol/sdk/types.js'
+import { FirebaseClient } from './client.js'
+import {
+  taskGetStatusTool,
+  handleTaskGetStatus,
+  taskGetNextStepTool,
+  handleTaskGetNextStep,
+  // ... import all tools
+} from './tools/index.js'
+
+export interface ServerOptions {
+  name?: string
+  version?: string
+}
+
+export function createServer(
+  userId: string,
+  options: ServerOptions = {}
+): Server {
+  if (!userId) {
+    throw new Error('userId is required')
+  }
+  
+  // Initialize Firebase client for this user
+  const client = new FirebaseClient(userId)
+  
+  // Create MCP server
+  const server = new Server(
+    {
+      name: options.name || 'task-mcp',
+      version: options.version || '0.1.0'
+    },
+    {
+      capabilities: {
+        tools: {}
+      }
+    }
+  )
+  
+  // Register list_tools handler
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: [
+        taskGetStatusTool,
+        taskGetNextStepTool,
+        // ... all tool definitions
+      ]
+    }
+  })
+  
+  // Register call_tool handler
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params
+    
+    try {
+      let result: string
+      
+      switch (name) {
+        case 'task_get_status':
+          result = await handleTaskGetStatus(client, args)
+          break
+        
+        case 'task_get_next_step':
+          result = await handleTaskGetNextStep(client, args)
+          break
+        
+        // ... all tool handlers
+        
+        default:
+          throw new McpError(
+            ErrorCode.MethodNotFound,
+            `Unknown tool: ${name}`
+          )
+      }
+      
+      return {
+        content: [
+          {
+            type: 'text',
+            text: result
+          }
+        ]
+      }
+    } catch (error) {
+      if (error instanceof McpError) {
+        throw error
+      }
+      
+      throw new McpError(
+        ErrorCode.InternalError,
+        `Tool execution failed: ${error instanceof Error ? error.message : String(error)}`
+      )
+    }
+  })
+  
+  return server
+}
+```
+
+## Files to Create
+
+- `src/server-factory.ts`
+- `src/server-factory.spec.ts`
+- `src/server.ts`
+- `src/index.ts`
+- `src/types.ts`
+
+---
+
+**Next Task**: [Task 91: Build Configuration](task-91-build-configuration.md)

package/agent/tasks/task-90-build-configuration.md

@@ -0,0 +1,146 @@
+# Task 91: Build Configuration
+
+**Milestone**: Milestone 2 - MCP Server Foundation
+**Estimated Time**: 4 hours
+**Dependencies**: Task 90 (MCP Server Implementation)
+**Status**: Not Started
+
+---
+
+## Objective
+
+Create esbuild configuration for bundling the MCP server for deployment. Set up both build and watch modes following the MCP Server Bootstrap Pattern.
+
+## Steps
+
+### 1. Install esbuild
+
+```bash
+npm install --save-dev esbuild
+```
+
+### 2. Create Build Script
+
+Create `esbuild.build.js`:
+- Bundle `src/server.ts` for standalone deployment
+- Bundle `src/server-factory.ts` for library usage
+- Target Node.js 20
+- ESM format
+- External dependencies: firebase-admin, @modelcontextprotocol/sdk
+- Generate source maps
+- Generate TypeScript declarations
+
+### 3. Create Watch Script
+
+Create `esbuild.watch.js`:
+- Same configuration as build script
+- Enable watch mode for development
+- Auto-rebuild on file changes
+
+### 4. Update package.json Scripts
+
+Add build scripts:
+```json
+{
+  "scripts": {
+    "build": "node esbuild.build.js",
+    "build:watch": "node esbuild.watch.js",
+    "clean": "rm -rf dist",
+    "dev": "npm run build:watch"
+  }
+}
+```
+
+### 5. Test Build
+
+Run build and verify:
+- `npm run build` succeeds
+- `dist/server.js` created
+- `dist/server-factory.js` created
+- Type declarations generated
+- No build errors
+
+## Verification
+
+- [ ] esbuild.build.js created
+- [ ] esbuild.watch.js created
+- [ ] Build succeeds without errors
+- [ ] dist/ directory contains bundled files
+- [ ] TypeScript declarations generated
+- [ ] Source maps generated
+- [ ] Watch mode works for development
+- [ ] Bundle size is reasonable
+
+## Example Build Script
+
+```javascript
+// esbuild.build.js
+import * as esbuild from 'esbuild';
+import { execSync } from 'child_process';
+
+// Build standalone server
+await esbuild.build({
+  entryPoints: ['src/server.ts'],
+  bundle: true,
+  platform: 'node',
+  target: 'node20',
+  format: 'esm',
+  outfile: 'dist/server.js',
+  sourcemap: true,
+  external: [
+    'firebase-admin',
+    '@modelcontextprotocol/sdk'
+  ],
+  banner: {
+    js: "import { createRequire } from 'module'; const require = createRequire(import.meta.url);"
+  },
+  alias: {
+    '@': './src'
+  }
+});
+
+// Build server factory
+await esbuild.build({
+  entryPoints: ['src/server-factory.ts'],
+  bundle: true,
+  platform: 'node',
+  target: 'node20',
+  format: 'esm',
+  outfile: 'dist/server-factory.js',
+  sourcemap: true,
+  external: [
+    'firebase-admin',
+    '@modelcontextprotocol/sdk'
+  ],
+  banner: {
+    js: "import { createRequire } from 'module'; const require = createRequire(import.meta.url);"
+  },
+  alias: {
+    '@': './src'
+  }
+});
+
+console.log('✓ JavaScript bundles built');
+
+// Generate TypeScript declarations
+console.log('Generating TypeScript declarations...');
+try {
+  execSync('tsc --emitDeclarationOnly --outDir dist', { stdio: 'inherit' });
+  console.log('✓ TypeScript declarations generated');
+} catch (error) {
+  console.error('✗ Failed to generate TypeScript declarations');
+  process.exit(1);
+}
+
+console.log('✓ Build complete');
+```
+
+## Files to Create
+
+- `esbuild.build.js`
+- `esbuild.watch.js`
+- Update `package.json` scripts
+
+---
+
+**Next Task**: [Task 92: Deployment Configuration](task-92-deployment-configuration.md)

package/agent/tasks/task-91-deployment-configuration.md

@@ -0,0 +1,128 @@
+# Task 92: Deployment Configuration
+
+**Milestone**: Milestone 2 - MCP Server Foundation
+**Estimated Time**: 4 hours
+**Dependencies**: Task 91 (Build Configuration)
+**Status**: Not Started
+
+---
+
+## Objective
+
+Create deployment configuration for running task-mcp MCP server on Cloud Run or other platforms. Set up environment variables, service account configuration, and deployment scripts.
+
+## Steps
+
+### 1. Create Environment Configuration
+
+Create `.env.example`:
+```bash
+# Firebase Configuration
+FIREBASE_PROJECT_ID=your-project-id
+FIREBASE_SERVICE_ACCOUNT_PATH=./service-account.json
+# Or use JSON directly:
+# FIREBASE_SERVICE_ACCOUNT_JSON={"type":"service_account",...}
+
+# Server Configuration
+NODE_ENV=production
+LOG_LEVEL=info
+```
+
+### 2. Create Dockerfile
+
+Create `Dockerfile`:
+- Use Node.js 20 base image
+- Copy package files and install dependencies
+- Copy source code
+- Build the project
+- Set up entrypoint for server
+- Expose necessary ports (if using SSE)
+
+### 3. Create Cloud Run Configuration
+
+Create `cloudrun.yaml`:
+- Service name: task-mcp
+- Region: us-central1
+- Memory: 512Mi
+- CPU: 1
+- Min instances: 0
+- Max instances: 10
+- Environment variables
+- Service account
+
+### 4. Create Deployment Script
+
+Create `scripts/deploy.sh`:
+- Build Docker image
+- Push to Google Container Registry
+- Deploy to Cloud Run
+- Set environment variables
+- Configure service account
+
+### 5. Update .gitignore
+
+Add to `.gitignore`:
+- `service-account.json`
+- `.env`
+- `.env.local`
+- `dist/`
+- `coverage/`
+
+### 6. Create README
+
+Create `README.md`:
+- Project description
+- Installation instructions
+- Configuration guide
+- Deployment guide
+- Usage examples
+
+## Verification
+
+- [ ] .env.example created
+- [ ] Dockerfile builds successfully
+- [ ] Cloud Run configuration valid
+- [ ] Deployment script works
+- [ ] .gitignore updated
+- [ ] README.md complete
+- [ ] Service account not in git
+- [ ] Environment variables documented
+
+## Example Dockerfile
+
+```dockerfile
+FROM node:20-alpine
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm ci --only=production
+
+# Copy source code
+COPY . .
+
+# Build the project
+RUN npm run build
+
+# Set environment
+ENV NODE_ENV=production
+
+# Run the server
+CMD ["node", "dist/server.js"]
+```
+
+## Files to Create
+
+- `Dockerfile`
+- `.env.example`
+- `cloudrun.yaml`
+- `scripts/deploy.sh`
+- `README.md`
+- Update `.gitignore`
+
+---
+
+**Next Task**: Milestone 2 Complete! → [Milestone 3: agentbase.me Integration](../milestones/milestone-3-agentbase-integration.md)

package/coverage/base.css

@@ -0,0 +1,224 @@
+body, html {
+  margin:0; padding: 0;
+  height: 100%;
+}
+body {
+    font-family: Helvetica Neue, Helvetica, Arial;
+    font-size: 14px;
+    color:#333;
+}
+.small { font-size: 12px; }
+*, *:after, *:before {
+  -webkit-box-sizing:border-box;
+     -moz-box-sizing:border-box;
+          box-sizing:border-box;
+  }
+h1 { font-size: 20px; margin: 0;}
+h2 { font-size: 14px; }
+pre {
+    font: 12px/1.4 Consolas, "Liberation Mono", Menlo, Courier, monospace;
+    margin: 0;
+    padding: 0;
+    -moz-tab-size: 2;
+    -o-tab-size:  2;
+    tab-size: 2;
+}
+a { color:#0074D9; text-decoration:none; }
+a:hover { text-decoration:underline; }
+.strong { font-weight: bold; }
+.space-top1 { padding: 10px 0 0 0; }
+.pad2y { padding: 20px 0; }
+.pad1y { padding: 10px 0; }
+.pad2x { padding: 0 20px; }
+.pad2 { padding: 20px; }
+.pad1 { padding: 10px; }
+.space-left2 { padding-left:55px; }
+.space-right2 { padding-right:20px; }
+.center { text-align:center; }
+.clearfix { display:block; }
+.clearfix:after {
+  content:'';
+  display:block;
+  height:0;
+  clear:both;
+  visibility:hidden;
+  }
+.fl { float: left; }
+@media only screen and (max-width:640px) {
+  .col3 { width:100%; max-width:100%; }
+  .hide-mobile { display:none!important; }
+}
+
+.quiet {
+  color: #7f7f7f;
+  color: rgba(0,0,0,0.5);
+}
+.quiet a { opacity: 0.7; }
+
+.fraction {
+  font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace;
+  font-size: 10px;
+  color: #555;
+  background: #E8E8E8;
+  padding: 4px 5px;
+  border-radius: 3px;
+  vertical-align: middle;
+}
+
+div.path a:link, div.path a:visited { color: #333; }
+table.coverage {
+  border-collapse: collapse;
+  margin: 10px 0 0 0;
+  padding: 0;
+}
+
+table.coverage td {
+  margin: 0;
+  padding: 0;
+  vertical-align: top;
+}
+table.coverage td.line-count {
+    text-align: right;
+    padding: 0 5px 0 20px;
+}
+table.coverage td.line-coverage {
+    text-align: right;
+    padding-right: 10px;
+    min-width:20px;
+}
+
+table.coverage td span.cline-any {
+    display: inline-block;
+    padding: 0 5px;
+    width: 100%;
+}
+.missing-if-branch {
+    display: inline-block;
+    margin-right: 5px;
+    border-radius: 3px;
+    position: relative;
+    padding: 0 4px;
+    background: #333;
+    color: yellow;
+}
+
+.skip-if-branch {
+    display: none;
+    margin-right: 10px;
+    position: relative;
+    padding: 0 4px;
+    background: #ccc;
+    color: white;
+}
+.missing-if-branch .typ, .skip-if-branch .typ {
+    color: inherit !important;
+}
+.coverage-summary {
+  border-collapse: collapse;
+  width: 100%;
+}
+.coverage-summary tr { border-bottom: 1px solid #bbb; }
+.keyline-all { border: 1px solid #ddd; }
+.coverage-summary td, .coverage-summary th { padding: 10px; }
+.coverage-summary tbody { border: 1px solid #bbb; }
+.coverage-summary td { border-right: 1px solid #bbb; }
+.coverage-summary td:last-child { border-right: none; }
+.coverage-summary th {
+  text-align: left;
+  font-weight: normal;
+  white-space: nowrap;
+}
+.coverage-summary th.file { border-right: none !important; }
+.coverage-summary th.pct { }
+.coverage-summary th.pic,
+.coverage-summary th.abs,
+.coverage-summary td.pct,
+.coverage-summary td.abs { text-align: right; }
+.coverage-summary td.file { white-space: nowrap;  }
+.coverage-summary td.pic { min-width: 120px !important;  }
+.coverage-summary tfoot td { }
+
+.coverage-summary .sorter {
+    height: 10px;
+    width: 7px;
+    display: inline-block;
+    margin-left: 0.5em;
+    background: url(sort-arrow-sprite.png) no-repeat scroll 0 0 transparent;
+}
+.coverage-summary .sorted .sorter {
+    background-position: 0 -20px;
+}
+.coverage-summary .sorted-desc .sorter {
+    background-position: 0 -10px;
+}
+.status-line {  height: 10px; }
+/* yellow */
+.cbranch-no { background: yellow !important; color: #111; }
+/* dark red */
+.red.solid, .status-line.low, .low .cover-fill { background:#C21F39 }
+.low .chart { border:1px solid #C21F39 }
+.highlighted,
+.highlighted .cstat-no, .highlighted .fstat-no, .highlighted .cbranch-no{
+  background: #C21F39 !important;
+}
+/* medium red */
+.cstat-no, .fstat-no, .cbranch-no, .cbranch-no { background:#F6C6CE }
+/* light red */
+.low, .cline-no { background:#FCE1E5 }
+/* light green */
+.high, .cline-yes { background:rgb(230,245,208) }
+/* medium green */
+.cstat-yes { background:rgb(161,215,106) }
+/* dark green */
+.status-line.high, .high .cover-fill { background:rgb(77,146,33) }
+.high .chart { border:1px solid rgb(77,146,33) }
+/* dark yellow (gold) */
+.status-line.medium, .medium .cover-fill { background: #f9cd0b; }
+.medium .chart { border:1px solid #f9cd0b; }
+/* light yellow */
+.medium { background: #fff4c2; }
+
+.cstat-skip { background: #ddd; color: #111; }
+.fstat-skip { background: #ddd; color: #111 !important; }
+.cbranch-skip { background: #ddd !important; color: #111; }
+
+span.cline-neutral { background: #eaeaea; }
+
+.coverage-summary td.empty {
+    opacity: .5;
+    padding-top: 4px;
+    padding-bottom: 4px;
+    line-height: 1;
+    color: #888;
+}
+
+.cover-fill, .cover-empty {
+  display:inline-block;
+  height: 12px;
+}
+.chart {
+  line-height: 0;
+}
+.cover-empty {
+    background: white;
+}
+.cover-full {
+    border-right: none !important;
+}
+pre.prettyprint {
+    border: none !important;
+    padding: 0 !important;
+    margin: 0 !important;
+}
+.com { color: #999 !important; }
+.ignore-none { color: #999; font-weight: normal; }
+
+.wrapper {
+  min-height: 100%;
+  height: auto !important;
+  height: 100%;
+  margin: 0 auto -48px;
+}
+.footer, .push {
+  height: 48px;
+}