What is Duke Mcp Tools

Duke MCP (Multi-purpose Communication Protocol) is a unified backend server that facilitates natural language access to various Duke University services through OpenWebUI, allowing users to interact with university resources using conversational queries.

Use cases

Use cases include querying campus events through natural language, retrieving contact information for community members, and simplifying access to various university resources without navigating complex APIs.

How to use

Users can access the Duke MCP through the OpenWebUI interface, where they can input natural language queries related to university services, such as event calendars and directory information.

Key features

Key features include natural language time parsing, event filtering and categorization, simplified data representation, intelligent handling of large result sets, and efficient caching for directory searches.

Where to use

Duke MCP can be used in educational institutions, particularly for enhancing user interaction with university services, improving accessibility to information, and streamlining communication processes.

Duke MCP (Multi-purpose Communication Protocol)

Project Overview

The Duke MCP is a unified backend server that provides natural language access to various Duke University services through OpenWebUI. This system allows users to interact with university resources through simple, conversational queries rather than navigating complex APIs or web interfaces.

The MCP acts as a middleware layer between Duke’s existing data services and the Large Language Model (LLM) interface, providing intelligent caching, data transformation, and integration between systems.

Core Components

The Duke MCP currently integrates three main services:

1. Calendar MCP

The Calendar MCP provides access to Duke’s event calendar system, allowing natural language queries about campus events.

Key Features:

• Natural language time parsing (e.g., “this weekend”, “next Monday”)
• Event filtering and categorization
• Simplified data representation to reduce token usage
• Intelligent handling of large result sets

Strategy:
Our Calendar MCP approach addresses several challenges with the Duke calendar system:

• Data Volume & Quality: We handle thousands of groups/sponsors (many orphaned), hundreds of ad-hoc categories, and inconsistent data entry by implementing a streamlined data model. The data feed is so bad and a nightmare to work with.
• Complex Hierarchies: Rather than struggling with traditional filtering approaches, we leverage the LLM’s abilities to understand query intent and match relevant events.
• Time-bound Data: We provide native time expression handling to convert natural language to API parameters.

2. Directory MCP

The Directory MCP connects to Duke’s LDAP directory service, making it easy to find contact information for Duke community members.

Key Features:

• Name and NetID-based search
• Detailed contact information retrieval
• Efficient caching to reduce load on Duke LDAP services
• Privacy-conscious data presentation

Strategy:
The Directory MCP takes a straightforward approach to providing contact information:

• Data Simplification: We extract and present only the most useful contact details.
• Efficient Caching: Directory information changes infrequently, so aggressive caching reduces load on Duke systems.
• Name Resolution: We optimize for the most common use case - finding someone by name - with fallbacks to NetID search.

3. Scholars MCP

The Scholars MCP provides access to Duke’s scholarly database, enabling queries about research, publications, and grants.

Key Features:

• Integration with Directory for DUID lookup
• Publication and grant information retrieval
• Research profile access
• Complex data extraction and formatting

Strategy:
The Scholars MCP addresses unique challenges:

• Two-stage Lookup: We handle the complexity of first finding a DUID from the Directory and then using it for Scholars queries, making this transparent to users.
• Data Complexity: The Scholars API returns deeply nested, complex data structures that we intelligently parse to extract the most relevant information.
• Connected Presentation: We connect biographical information with research interests, publications, and grants to create comprehensive profiles.

Technical Architecture

Core Design Principles

1. Modular Components: Each service has dedicated models, MCP implementation, and routes.
2. Shared Infrastructure: All components run on the same server with consistent patterns.
3. Intelligent Caching: Time-based caching reduces load on Duke’s services.
4. Native Function Support: Optimized for OpenWebUI’s native function capabilities.

Server Structure

duke-mcp/
├── app/
│   ├── mcp/
│   │   ├── __init__.py
│   │   ├── calendar.py
│   │   ├── directory.py
│   │   └── scholars.py
│   ├── models/
│   │   ├── __init__.py
│   │   ├── calendar.py
│   │   ├── directory.py
│   │   └── scholars.py
│   ├── routers/
│   │   ├── calendar.py
│   │   ├── directory.py
│   │   └── scholars.py
│   ├── __init__.py
│   ├── config.py
│   └── main.py
├── duke_calendar_tool.py
├── duke_directory_tool.py
├── duke_scholars_tool.py
├── requirements.txt
├── .env
└── README.md

Component Architecture

Each service component follows the same architecture pattern:

1. Models: Define data structures for API requests and responses
2. MCP Implementation: Business logic, API communication, and caching
3. API Routes: FastAPI endpoints for accessing the service
4. OpenWebUI Tool: Client-side tool for interacting with the MCP

Caching Strategy

To reduce load on Duke’s services and improve performance, we implement a time-based caching system:

• TTL-based Cache: Data is cached with a configurable time-to-live (default: 1 hour)
• Cache Keys: Structured to allow granular invalidation
• Service-specific Caching: Each MCP component implements caching tailored to its data patterns

OpenWebUI Integration

Native Functions

Each MCP component is paired with an OpenWebUI tool that provides:

1. Specialized functions for service-specific queries
2. Clear instructions for the LLM
3. Error handling and fallback strategies
4. User-friendly response formatting

LLM Strategy

Our approach to working with the LLM includes:

• Clear Instructions: Well-defined usage steps for each tool
• Contextual Examples: Common query patterns to guide the LLM
• Formatting Guidelines: How to present different types of results
• Educational Prompts: Helping the LLM understand the domain context

Installation and Setup

Prerequisites

• Python 3.8 or higher
• FastAPI and Uvicorn
• Access to Duke API services

Configuration

Create a .env file with the following variables:

# General settings
DEBUG=False
REFERENCE_CACHE_TTL=3600

# Calendar API
DUKE_CALENDAR_API_URL=https://calendar.duke.edu/events/index.json

# Directory API
DUKE_DIRECTORY_API_KEY=your_directory_api_key
DUKE_DIRECTORY_BASE_URL=https://streamer.oit.duke.edu/ldap/people

# Scholars API
DUKE_SCHOLARS_BASE_URL=https://scholars.duke.edu/widgets/api/v0.9

Running the Server

uvicorn app.main:app --host 0.0.0.0 --port 8000

For production, you may want to use Gunicorn with Uvicorn workers:

gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000

OpenWebUI Tool Setup

1. Import each tool file into your OpenWebUI installation
2. Update the mcp_url in each tool to point to your MCP server

API Documentation

Interactive API documentation is available at /docs when the server is running.

Calendar Endpoints

• GET /api/v1/calendar/simplified-events: Get events for a date range
• POST /api/v1/calendar/events-by-local-ids: Get full event details by IDs

Directory Endpoints

• GET /api/v1/directory/search: Search the directory
• GET /api/v1/directory/person/{ldapkey}: Get detailed person information
• GET /api/v1/directory/netid/{netid}: Search by NetID
• GET /api/v1/directory/name/{name}: Search by name

Scholars Endpoints

• GET /api/v1/scholars/details: Get scholar profile
• GET /api/v1/scholars/publications: Get scholar publications
• GET /api/v1/scholars/grants: Get scholar grants

Future Development

Planned Components

1. Course MCP: Access to course information and schedules
2. Maps MCP: Building locations and directions
3. Dining MCP: Dining locations and menus

Roadmap

1. Enhanced Integration: Deeper connections between components (e.g., event locations linked to maps)
2. Advanced Caching: More sophisticated cache strategies with selective invalidation
3. Personalization: User-specific customization and preferences
4. Analytics: Usage tracking to improve service quality

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.