# MCP PostgreSQL Server
A FastMCP server for user name resolution with PostgreSQL backend.
## Prerequisites
```bash
pip install -r requirements.txt
```
Ensure `.env` file contains database credentials and auth token:
```
DB_HOST=your_host
DB_PORT=5432
DB_NAME=your_database
DB_USER=your_user
DB_PASSWORD=your_password
# Authentication (optional for STDIO, recommended for HTTP)
MCP_AUTH_TOKEN=your-secret-token-here
```
---
## 1. Running with STDIO Transport
### a) Development Mode (with MCP Inspector)
```bash
fastmcp dev server.py
```
This launches MCP Inspector automatically in your browser for interactive testing.
### b) Direct Mode
```bash
fastmcp run server.py
```
Or:
```bash
python server.py
```
---
## 2. Running with HTTP Transport
### a) Start the HTTP Server
```bash
python server.py --http
```
Server starts at: `http://localhost:8000/mcp`
### b) Launch MCP Inspector
Open a new terminal:
```bash
npx @modelcontextprotocol/inspector
```
### c) Connect to Server in MCP Inspector
1. Change **Transport Type** to: `Streamable HTTP`
2. Enter **URL**: `http://localhost:8000/mcp`
3. Click **Connect**
---
## 3. Authentication
If `MCP_AUTH_TOKEN` is set in `.env`, all HTTP requests must include the token.
| `MCP_AUTH_TOKEN` | Behavior |
|------------------|----------|
| **Not set** | No authentication (open access) |
| **Set** | All requests require `Authorization: Bearer <token>` |
### In MCP Inspector (HTTP)
1. Select **Transport Type**: `Streamable HTTP`
2. Enter **URL**: `http://localhost:8000/mcp`
3. In the **Headers** section, add:
- **Header Name**: `Authorization`
- **Header Value**: `Bearer your-secret-token-here`
4. Click **Connect**
Without the correct token, you'll receive `401 Unauthorized`.
### In LangChain/LangGraph
```python
from langchain_mcp_adapters.client import MultiServerMCPClient
client = MultiServerMCPClient({
"user_resolver": {
"transport": "streamable_http",
"url": "http://localhost:8000/mcp",
"headers": {
"Authorization": "Bearer your-secret-token-here"
}
}
})
```
### In FastMCP Client (Python)
```python
from fastmcp import Client
from fastmcp.client.auth import BearerAuth
client = Client(
"http://localhost:8000/mcp",
auth=BearerAuth("your-secret-token-here")
)
```
---
## 4. Claude Desktop Integration (Free Version)
Claude Desktop free version only supports STDIO transport. Use the **proxy server** to bridge to your HTTP server.
### Architecture
```
Claude Desktop ←→ proxy_server.py (STDIO) ←→ server.py (HTTP)
```
### Setup Steps
#### Step 1: Start the HTTP Server
```bash
python server.py --http
```
#### Step 2: Run the Proxy Server (Optional - for manual testing)
```bash
C:\Users\shubhammishra_remote\AppData\Local\Programs\Python\Python310\Scripts\uv run proxy_server.py
```
#### Step 3: Configure Claude Desktop
Edit the Claude Desktop config file:
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
Add this configuration:
```json
{
"mcpServers": {
"Efforti Name Resolver": {
"command": "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\Programs\\Python\\Python310\\Scripts\\uv",
"args": [
"--directory",
"D:\\MemoryCloud\\mcp-development",
"run",
"proxy_server.py"
],
"env": {
"MCP_SERVER_URL": "http://localhost:8000/mcp",
"MCP_AUTH_TOKEN": "your-secret-token-here"
},
"transport": "stdio"
}
}
}
```
> **Important:**
> - Replace `YOUR_USERNAME` with your actual Windows username. Find your `uv` path with: `where uv`
> - Replace `your-secret-token-here` with the actual `MCP_AUTH_TOKEN` from your `.env` file
> - The `env` variables are **required** for the proxy to connect to the HTTP server
#### Step 4: Restart Claude Desktop
Close and reopen Claude Desktop. Look for the **hammer icon (🔨)** in the input box.
#### Step 5: Test
Ask Claude:
> "Use the resolve_user tool to find shubham mishra"
---
## Available Tools
### Quick Reference
| # | Tool | Input(s) | Purpose |
|---|------|----------|---------|
| 1 | `resolve_user` | `name_or_email: str` | Fuzzy find user → UUID |
| 2 | `resolve_users_batch` | `names: list[str]` | Batch fuzzy find |
| 3 | `confirm_user` | `email: str` | Exact email → UUID |
| 4 | `confirm_users_batch` | `emails: list[str]` | Batch exact email lookup |
| 5 | `get_team_members` | `manager_identifier: str` | Get all reports of manager |
| 6 | `get_manager_of_user` | `user_identifier: str` | Get user's manager(s) |
| 7 | `get_user_by_uuid` | `user_uuid: str` | UUID → full user details |
| 8 | `resolve_user_in_team` | `name_or_email: str`, `manager_identifier: str` | Scoped search within team |
| 9 | `get_user_calendar_insights` | `user_identifier: str`, `date?`, `start_date?`, `end_date?` | Complete calendar dashboard |
| 10 | `query_user_meetings` | `user_identifier: str`, `start_date`, `end_date`, filters... | Find/filter/sort meetings |
| 11 | `get_meeting_details` | `event_id: str` | Full meeting details with attendees |
---
### Category 1: User Resolution Tools
#### 1. `resolve_user`
**Description:**
Resolve a user name or email to their UUID using fuzzy matching. Returns the user's UUID if confidently resolved, or asks for verification/disambiguation if uncertain.
**Input Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name_or_email` | `string` | ✅ | The user's name or email to resolve. Can be full name, partial name, email, or email prefix. |
**Example:**
```python
resolve_user("john doe")
resolve_user("john.doe@company.com")
resolve_user("joh") # partial match
```
---
#### 2. `resolve_users_batch`
**Description:**
Resolve multiple user names or emails to their UUIDs in a single call. Efficiently processes a batch and returns results for each input.
**Input Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `names` | `list[string]` | ✅ | List of names or emails to resolve. Maximum 50 items. |
**Example:**
```python
resolve_users_batch(["john doe", "jane smith", "bob@company.com"])
```
---
#### 3. `confirm_user`
**Description:**
Confirm a user by their exact email and get their UUID. Use this after verification/disambiguation when the user has confirmed which email is correct.
**Input Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `email` | `string` | ✅ | The exact email address to look up. |
**Example:**
```python
confirm_user("john.doe@company.com")
```
---
#### 4. `confirm_users_batch`
**Description:**
Confirm multiple users by their exact emails and get their UUIDs. More efficient than calling `confirm_user` multiple times.
**Input Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `emails` | `list[string]` | ✅ | List of exact email addresses to look up. Maximum 50 items. |
**Example:**
```python
confirm_users_batch(["john@company.com", "jane@company.com", "bob@company.com"])
```
---
### Category 2: Team Management Tools
#### 5. `get_team_members`
**Description:**
Get all team members under a specific manager. Retrieves all users who report to the specified manager (including users under them as remote manager).
**Input Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `manager_identifier` | `string` | ✅ | Manager's email (preferred), UUID, or name. Email is most reliable for exact matches. |
**Example:**
```python
get_team_members("john.manager@company.com")
get_team_members("550e8400-e29b-41d4-a716-446655440000")
get_team_members("John Manager") # name search
```
---
#### 6. `get_manager_of_user`
**Description:**
Get the manager(s) of a specific user. Returns both primary manager and remote manager if applicable.
**Input Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_identifier` | `string` | ✅ | User's email (preferred) or UUID. |
**Example:**
```python
get_manager_of_user("employee@company.com")
get_manager_of_user("550e8400-e29b-41d4-a716-446655440000")
```
---
#### 7. `get_user_by_uuid`
**Description:**
Get complete user details by their UUID. Use this for quick lookups when you already have the UUID from a previous resolution.
**Input Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_uuid` | `string` | ✅ | The user's UUID. Format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
**Example:**
```python
get_user_by_uuid("550e8400-e29b-41d4-a716-446655440000")
```
---
#### 8. `resolve_user_in_team`
**Description:**
Resolve a user name/email within a specific manager's team only. This is a SCOPED search that only returns users who report to the specified manager. Use for security/relevance when searches should stay within team boundaries.
**Input Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name_or_email` | `string` | ✅ | The user's name or email to search for. |
| `manager_identifier` | `string` | ✅ | Manager's email (preferred) or UUID to scope the search. |
**Example:**
```python
resolve_user_in_team("john", "team.manager@company.com")
resolve_user_in_team("john.doe@company.com", "550e8400-e29b-41d4-a716-446655440000")
```
---
### Category 3: Calendar Insights Tools
#### 9. `get_user_calendar_insights`
**Description:**
Get comprehensive calendar insights for a user - the complete dashboard. Provides health assessment, metrics, statistical extremes (longest/shortest/largest meetings), recurring meeting analysis, and quality metrics.
**Input Parameters:**
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `user_identifier` | `string` | ✅ | - | User's email (preferred) or UUID. |
| `date` | `string` | ❌ | - | Single date (YYYY-MM-DD) for day view. If provided, ignores start/end. |
| `start_date` | `string` | ❌ | Last 7 days | Range start (YYYY-MM-DD). |
| `end_date` | `string` | ❌ | Today | Range end (YYYY-MM-DD). Max range: 90 days. |
| `include_daily` | `boolean` | ❌ | `false` | Include daily breakdown array. |
| `include_meetings` | `boolean` | ❌ | `false` | Include list of actual meetings. |
**Returns:**
- `health`: Status (healthy/warning/at_risk), concerns, positives, suggestions
- `time`: Total meeting hours, focus hours, percentages
- `averages`: Per-day metrics (meeting load %, focus minutes, meetings/day)
- `by_type`: Breakdown by meeting type (1:1, standup, review, planning, external)
- `recurring`: Recurring meeting count, percentage, top series
- `quality`: Agenda coverage, average quality, large meetings count
- `extremes`: Longest/shortest/largest meetings, busiest/lightest days
**Example:**
```python
get_user_calendar_insights("john@company.com", date="2025-12-12")
get_user_calendar_insights("john@company.com", start_date="2025-12-01", end_date="2025-12-31")
get_user_calendar_insights("john@company.com", include_meetings=True)
```
---
#### 10. `query_user_meetings`
**Description:**
Query user's meetings with flexible filtering and sorting. Use this to find specific meetings, get sorted lists (longest, shortest, largest), filter by criteria, or search by title keyword.
**Input Parameters:**
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `user_identifier` | `string` | ✅ | - | User's email (preferred) or UUID. |
| `start_date` | `string` | ✅ | - | Start date (YYYY-MM-DD). |
| `end_date` | `string` | ✅ | - | End date (YYYY-MM-DD). |
| `sort_by` | `string` | ❌ | `start_time` | Sort field: `start_time`, `duration`, `attendees`, `agenda_quality`. |
| `order` | `string` | ❌ | `desc` | Sort order: `asc` or `desc`. |
| `limit` | `integer` | ❌ | `20` | Max results (max: 100). |
| `meeting_type` | `string` | ❌ | - | Filter: `1_1`, `STANDUP`, `REVIEW`, `PLANNING`, `EXTERNAL`, `OTHER`. |
| `is_external` | `boolean` | ❌ | - | Filter by external flag. |
| `is_recurring` | `boolean` | ❌ | - | Filter by recurring flag. |
| `has_agenda` | `boolean` | ❌ | - | Filter by agenda presence. |
| `min_duration` | `integer` | ❌ | - | Minimum duration in minutes. |
| `min_attendees` | `integer` | ❌ | - | Minimum attendee count. |
| `search` | `string` | ❌ | - | Title keyword search (case-insensitive). |
**Example:**
```python
# Find longest meeting
query_user_meetings("john@company.com", "2025-12-01", "2025-12-31", sort_by="duration", order="desc", limit=1)
# Find shortest meeting
query_user_meetings("john@company.com", "2025-12-01", "2025-12-31", sort_by="duration", order="asc", limit=1)
# Search by title
query_user_meetings("john@company.com", "2025-12-01", "2025-12-31", search="sprint planning")
# Filter recurring meetings
query_user_meetings("john@company.com", "2025-12-01", "2025-12-31", is_recurring=True)
# Find meetings without agenda
query_user_meetings("john@company.com", "2025-12-01", "2025-12-31", has_agenda=False)
# Large meetings (>10 attendees)
query_user_meetings("john@company.com", "2025-12-01", "2025-12-31", min_attendees=10)
```
---
#### 11. `get_meeting_details`
**Description:**
Get full details of a specific meeting. Use the `event_id` from `query_user_meetings` or `get_user_calendar_insights` to get complete information including attendee list, organizer, and agenda quality signals.
**Input Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `event_id` | `string` | ✅ | The event ID from a previous query. |
**Returns:**
- `title`: Meeting title
- `organizer`: Organizer's email
- `time`: Start, end, date, duration_min
- `attendees`: Total count, internal/external counts, full attendee list
- `classification`: Meeting type, is_recurring, is_external, is_large_meeting
- `quality`: has_agenda, agenda_quality_index, agenda_signals
- `recurring_info`: series_id and instance_key (if recurring)
- `tagged_priorities`: Priority tags from title/description
**Example:**
```python
get_meeting_details("abc123_20251212T100000Z")
```
