MCP PostgreSQL Server

A FastMCP server for user name resolution with PostgreSQL backend.

Prerequisites

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)

fastmcp dev server.py

This launches MCP Inspector automatically in your browser for interactive testing.

b) Direct Mode

fastmcp run server.py

Or:

python server.py

---

2. Running with HTTP Transport

a) Start the HTTP Server

python server.py --http

Server starts at: http://localhost:8000/mcp

b) Launch MCP Inspector

Open a new terminal:

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

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)

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

python server.py --http

Step 2: Run the Proxy Server (Optional - for manual testing)

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:

{
  "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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

# 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:

get_meeting_details("abc123_20251212T100000Z")