Contract Manager MCP Server

A demonstration Model Context Protocol (MCP) server built with the official MCP TypeScript SDK. This server simulates a contract management system and showcases MCP capabilities including tools, resources, prompts, subscriptions, progress notifications, sampling, elicitation, and interactive UI cards.

Built with TypeScript, Express.js, SQLite, and @mcp-ui/server.

Quick Start

Prerequisites

• VS Code with Dev Containers extension
• Docker Desktop

Setup

1. Clone and open the repository:

   git clone <repository-url>
   cd contract-manager-mcp
   code .

2. Open in Dev Container:

   • VS Code will prompt: "Reopen in Container" → Click it
   • Or use Command Palette (Ctrl+Shift+P / Cmd+Shift+P):
     • Type: Dev Containers: Reopen in Container
   • Wait for container to build (~2-3 minutes first time)

3. Build the project:

   npm run build

Running the Server

The server supports three transport methods. stdio is recommended for most MCP clients.

stdio Transport (Recommended)

npm run dev:stdio

Best for:

• MCP Inspector testing
• Integration with Claude Desktop, Cursor, VS Code
• Local development and debugging

Streamable HTTP Transport

npm run dev:http

Runs on http://localhost:3000/mcp

Best for:

• Remote connections
• Web-based clients
• RESTful integrations

SSE Transport (Legacy)

npm run dev:sse

Runs on http://localhost:3000/sse

Note: SSE transport is deprecated in favor of Streamable HTTP.

Testing with MCP Inspector

The MCP Inspector is the official tool for testing MCP servers.

Option 1: Combined Start (Easiest)

# Start both server and inspector
npm run dev:stdio:with-inspector

The inspector will automatically open at http://localhost:6274 with authentication pre-configured.

Option 2: Manual Start

Terminal 1 - Start Server:

npm run dev:stdio

Terminal 2 - Start Inspector:

npm run inspector:container

Then open the URL shown in Terminal 2 (includes auth token).

Connecting in the Inspector

For stdio transport:

1. Click "Connect to Server"
2. Server Command: node
3. Arguments: dist/index-stdio.js
4. Click Connect

For HTTP transport:

1. Select "Streamable HTTP" transport
2. URL: http://localhost:3000/mcp
3. Click Connect

Testing with Nanobot

Nanobot is an AI agent that supports MCP servers with UI capabilities. Use this to interact with the server's interactive UI cards.

Prerequisites:

• OpenAI API key (required for Nanobot)

Setup:

1. Create a .env file in the project root with your OpenAI API key:

   OPENAI_API_KEY=your_openai_api_key_here

2. Build and run:

   npm run build
   npm run nanobot

The nanobot script automatically loads your API key from .env and starts Nanobot with the MCP server configured.

Interactive UI Cards Available:

• view_task - Interactive task card with completion tracking, employee assignment, and tag management
• view_employee - Employee profile with workload statistics and assigned tasks
• view_contract - Full contract dashboard with task filtering, sorting, and metrics

Available Scripts

Preferred for development with stdio transport

• npm run dev:stdio - stdio transport (recommended)
• npm run dev:stdio:with-inspector - Server + Inspector together

Other scripts are available, but these are the main ones

Project Overview

This server simulates a contract management system for demonstration purposes. It models a fictional organization managing:

• Programs - Top-level initiatives (e.g., "Digital Transformation")
• Contracts - Specific agreements within programs
• Tasks - Work items within contracts (with 0-10 completion tracking)
• Employees - Team members who can be assigned to tasks
• Tags - Categorization system for tasks

The database includes realistic sample data with friendly codes (E001, P001, C001, T001, TAG001) for easy reference.

MCP Capabilities

Tools (26 total)

Entity Management:

• List operations for all entities (employees, programs, contracts, tasks, tags)
• Get individual entities by code
• Full CRUD for tasks, employees, and tags
• Relationship management (assign employees/tags to tasks)

Progress Demonstration:

• run_really_long_task - Simulates long-running operations with progress notifications and cancellation support

Interactive UI Tools:

• view_task - Display interactive task card with completion, assignments, and tags
• view_employee - Display employee profile with workload metrics
• view_contract - Display contract dashboard with filtering and sorting

Find implementations in: src/tools/

Resources (10 total)

List Resources: Bulk access to all entities

• contract-manager://employees
• contract-manager://programs
• contract-manager://contracts
• contract-manager://tasks
• contract-manager://tags

Template Resources: Individual entity access with code completion

• contract-manager://employees/{code}
• contract-manager://programs/{code}
• contract-manager://contracts/{code}
• contract-manager://tasks/{code}
• contract-manager://tags/{code}

Subscriptions: Demonstrates MCP subscription protocol

• Subscribe to individual contracts: contract-manager://contracts/{code}
• Receive resources/updated notifications when contract or its tasks change

Find implementations in: src/resources/

Prompts (5 total)

• contract_analysis - Comprehensive contract analysis with risk assessment
• task_planning - AI-powered task suggestions and dependencies
• team_assignment - Intelligent employee assignment recommendations
• progress_review - Executive-level progress reports
• suggest_tags - Tag categorization suggestions

Sampling Example: suggest_tags prompt uses MCP sampling to request AI suggestions from the client

Find implementations in: src/prompts/

Advanced Features

Elicitation: Demonstrated in delete operations (tasks, employees, tags) which request user confirmation before proceeding

Progress Notifications: run_really_long_task tool shows proper progress token usage with step-by-step updates

Subscriptions: Contract resources support subscription with automatic notifications when contracts or their tasks change

Structured Content: All tools return both human-readable content and machine-readable JSON with output schemas

Annotations: Tools and resources include semantic hints (readOnly, destructive, priority, audience) for intelligent client behavior

Project Structure

contract-manager-mcp/
├── src/
│   ├── index-stdio.ts          # stdio transport entry
│   ├── index-http.ts           # HTTP transport entry
│   ├── index-sse.ts            # SSE transport entry
│   ├── contractManagerMCP.ts   # Main MCP server class
│   ├── tools/                  # MCP tools
│   │   ├── contractTools.ts
│   │   ├── taskTools.ts
│   │   ├── employeeTools.ts
│   │   ├── tagTools.ts
│   │   ├── programTools.ts
│   │   ├── progressTools.ts    # Progress demo
│   │   └── schemas/            # Tool schemas
│   ├── resources/              # MCP resources
│   │   ├── contractResources.ts
│   │   ├── taskResources.ts
│   │   └── ...
│   ├── prompts/                # MCP prompts
│   │   ├── contractAnalysis.ts
│   │   ├── taskPlanning.ts
│   │   └── ...
│   ├── ui/                     # UI components
│   │   ├── taskCard.ts         # Interactive task card
│   │   ├── employeeCard.ts     # Employee profile card
│   │   ├── contractDashboard.ts # Contract dashboard
│   │   └── styles/             # Shared styling
│   │       ├── constants.ts    # Color palette & dimensions
│   │       ├── loader.ts       # CSS file loader
│   │       ├── taskCard.css
│   │       ├── employeeCard.css
│   │       └── contractDashboard.css
│   ├── services/               # Business logic
│   ├── database/               # SQLite + Knex
│   ├── subscriptions/          # Subscription manager
│   ├── schemas/                # Zod validation
│   └── types/                  # TypeScript types
├── dist/                       # Compiled output
├── nanobot.yaml                # Nanobot config
├── run-nanobot.sh              # Nanobot launcher
├── package.json
├── tsconfig.json
└── README.md

Database

SQLite database with auto-initialization and seeding on startup.

Entities:

• Programs (P001, P002)
• Contracts (C001-C003)
• Tasks (T001-T007) with completion values 0-10
• Employees (E001-E005)
• Tags (TAG001-TAG008)

Features:

• Auto-generated friendly codes
• Cascade deletes
• Many-to-many relationships (employees-tasks, tags-tasks)
• Audit timestamps

UI Features

This server includes interactive UI cards powered by @mcp-ui/server:

Interactive Cards

Task Card (view_task tool):

• Real-time completion tracking (0-10 scale)
• Employee assignment/removal
• Tag management (add/remove)
• Visual progress indicators
• Contract and program context

Employee Card (view_employee tool):

• Contact information display
• Workload statistics (total, completed, in-progress, not-started)
• Overall completion rate with progress bar
• List of assigned tasks with quick view buttons

Contract Dashboard (view_contract tool):

• Contract overview with task metrics
• Overall completion percentage
• Task filtering (All, Completed, In Progress, Not Started)
• Sorting options (by name, by completion)
• Add Task, View, and Edit buttons
• Detailed contract information

Design System

• Color Palette: Monochromatic blue/cyan theme with 8 harmonious colors
• Typography: Lato font family from Google Fonts
• Architecture: Centralized styling constants for consistency
• Responsive: Frame sizes optimized for different card types
• Interactive: postMessage API for seamless tool communication

Technical Implementation

• Raw HTML: Self-contained cards with embedded CSS and JavaScript
• Communication: postMessage API for iframe-to-parent tool calls
• Styling: CSS variables generated from TypeScript constants
• Build Pipeline: Automatic CSS asset copying to dist folder

Environment Configuration

The .env file contains development defaults:

PORT=3000
NODE_ENV=development
CORS_ORIGIN=http://localhost:3000,http://localhost:8080

For Nanobot UI features, you must also add your OpenAI API key:

OPENAI_API_KEY=your_openai_api_key_here

Customize as needed and restart the server.

Development Container

The dev container includes:

• Node.js 22
• TypeScript and development tools
• VS Code extensions (TypeScript, ESLint, Prettier)
• Port forwarding (3000, 6274, 6277, 9229)
• Zsh with Oh My Zsh

Production Deployment

docker build -t contract-manager-mcp .
docker run -p 3000:3000 contract-manager-mcp

Contributing

1. Follow existing code style
2. Run npm run lint and npm run format before committing
3. Ensure TypeScript compiles: npm run build
4. Update documentation as needed

Resources

• MCP Documentation
• MCP Specification
• MCP TypeScript SDK
• MCP Inspector

License

• ISC

Troubleshooting

Inspector UI spinning/not loading:

• Ensure you're using npm run inspector:container in the dev container
• Check that ports 6274 and 6277 are forwarded in your devcontainer.json
• Try manually entering the proxy auth token in the Inspector configuration

Can't connect to MCP server:

• Verify your MCP server is running on http://localhost:3000/mcp
• Use "Streamable HTTP" transport type
• Check the browser console for CORS or network errors

Note: If you get connection issues, you may need to manually add the proxy auth token to the Inspector UI configuration.