Skip to content

Commit 21376d0

Browse files
pmbstylepmbstyle
committed
refactor, better transport, docker
1 parent ce97a40 commit 21376d0

File tree

15 files changed

+635
-595
lines changed

15 files changed

+635
-595
lines changed

‎Dockerfile‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
FROM python:3.12-slim AS builder
2+
3+
ARG POETRY_VERSION=1.8.2
4+
WORKDIR /app
5+
6+
RUN pip install "poetry==${POETRY_VERSION}"
7+
8+
RUN poetry config virtualenvs.in-project true
9+
10+
COPY pyproject.toml poetry.lock ./
11+
12+
RUN poetry install --no-root --only main
13+
14+
FROM python:3.12-slim
15+
16+
WORKDIR /app
17+
18+
COPY --from=builder /app/.venv /app/.venv
19+
20+
COPY src/ ./src
21+
COPY pyproject.toml poetry.lock README.md ./
22+
23+
RUN /app/.venv/bin/pip install -e .
24+
25+
ENV PATH="/app/.venv/bin:$PATH"
26+
27+
EXPOSE 8000
28+
29+
CMD ["python", "-m", "temporal_awareness_mcp.http_main"]

‎README.md‎

Lines changed: 235 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,249 @@
1-
# Temporal Awareness MCP
1+
# Temporal Awareness MCP Server
22

3-
A robust, modern, and well-tested MCP server that gives language models temporal awareness and time calculation abilities.
3+
A Model Context Protocol (MCP) server that provides AI agents with comprehensive temporal awareness and time calculation capabilities.
44

5-
This project provides a suite of reliable tools for an LLM to understand and reason about time, from simple date calculations to human-centric contextual analysis. It is built with modern Python (3.12+), Poetry for dependency management, and a strong emphasis on automated testing with pytest.
5+
## Features
66

7-
## 🚀 Getting Started
7+
- **Current Time**: Get current date and time in any timezone
8+
- **Time Calculations**: Calculate differences between timestamps
9+
- **Time Adjustments**: Add or subtract durations from timestamps
10+
- **Contextual Analysis**: Get human-readable context about timestamps
11+
- **Multiple Transports**: Support for both stdio (local) and HTTP (remote) connections
12+
- **Docker Support**: Ready for cloud deployment
13+
14+
## Quick Start
15+
16+
### For Local Development (Claude Desktop, Cursor)
17+
18+
1. **Install dependencies**:
19+
```bash
20+
git clone <repository-url>
21+
cd temporal-awareness-mcp
22+
poetry install
23+
```
24+
25+
2. **Run with stdio transport**:
26+
```bash
27+
poetry run python -m temporal_awareness_mcp.stdio_main
28+
```
29+
30+
### For Cloud Deployment
31+
32+
1. **Run with Docker**:
33+
```bash
34+
docker-compose up -d --build
35+
```
36+
37+
2. **Or run directly with HTTP transport**:
38+
```bash
39+
poetry run python -m temporal_awareness_mcp.http_main --host 0.0.0.0 --port 8000
40+
```
41+
42+
## Integration Guide
43+
44+
### Claude Desktop
45+
46+
Add to your Claude Desktop configuration file:
47+
48+
**For Windows:**
49+
```json
50+
{
51+
"mcpServers": {
52+
"temporal-awareness": {
53+
"command": "cmd",
54+
"args": ["/c", "cd /d \"C:\\path\\to\\temporal-awareness-mcp\" && poetry run python -m temporal_awareness_mcp.stdio_main"],
55+
"env": {}
56+
}
57+
}
58+
}
59+
```
60+
61+
**For macOS/Linux:**
62+
```json
63+
{
64+
"mcpServers": {
65+
"temporal-awareness": {
66+
"command": "sh",
67+
"args": ["-c", "cd '/path/to/temporal-awareness-mcp' && poetry run python -m temporal_awareness_mcp.stdio_main"],
68+
"env": {}
69+
}
70+
}
71+
}
72+
```
73+
74+
> **Important**: Replace `/path/to/temporal-awareness-mcp` with your actual project directory.
75+
76+
**Alternative: Using Python with PYTHONPATH**
77+
78+
If you prefer not to use Poetry:
79+
80+
```json
81+
{
82+
"mcpServers": {
83+
"temporal-awareness": {
84+
"command": "python",
85+
"args": ["-m", "temporal_awareness_mcp.stdio_main"],
86+
"env": {
87+
"PYTHONPATH": "/path/to/temporal-awareness-mcp/src"
88+
}
89+
}
90+
}
91+
}
92+
```
93+
94+
### Cursor IDE
95+
96+
Configure in Cursor Settings > Extensions > MCP:
97+
98+
```json
99+
{
100+
"servers": {
101+
"temporal-awareness": {
102+
"command": "poetry",
103+
"args": ["run", "python", "-m", "temporal_awareness_mcp.stdio_main"],
104+
"cwd": "/path/to/temporal-awareness-mcp"
105+
}
106+
}
107+
}
108+
```
109+
110+
### OpenAI and Cloud Clients
111+
112+
For cloud-based AI services, deploy the server and use HTTP transport:
113+
114+
1. **Deploy with ngrok (development)**:
115+
```bash
116+
# Terminal 1: Start the server
117+
docker-compose up -d --build
118+
119+
# Terminal 2: Expose with ngrok
120+
ngrok http 8000
121+
```
122+
123+
2. **Use the public URL in your MCP client**:
124+
```json
125+
{
126+
"type": "mcp",
127+
"server_label": "temporal-awareness",
128+
"server_url": "https://your-ngrok-url.ngrok.app/sse",
129+
"require_approval": "never"
130+
}
131+
```
132+
133+
3. **Production deployment**: Deploy to Railway, Heroku, Google Cloud Run, etc.
134+
135+
## Available Tools
136+
137+
### `get_current_time`
138+
Get the current date and time in a specified timezone.
139+
140+
**Parameters:**
141+
- `timezone` (string, optional): Timezone name (default: "UTC")
142+
- `format` (string, optional): Output format - "iso", "human", or "timestamp" (default: "iso")
143+
144+
**Example:**
145+
```
146+
What time is it in Tokyo?
147+
```
148+
149+
### `calculate_difference`
150+
Calculate the duration between two timestamps.
151+
152+
**Parameters:**
153+
- `start_time` (string): Start timestamp (ISO format or human readable)
154+
- `end_time` (string): End timestamp (ISO format or human readable)
155+
- `unit` (string, optional): Result unit - "seconds", "minutes", "hours", or "days" (default: "seconds")
156+
157+
**Example:**
158+
```
159+
How long is it from 9:00 AM to 5:30 PM?
160+
```
161+
162+
### `get_timestamp_context`
163+
Provide human-readable context about a timestamp.
164+
165+
**Parameters:**
166+
- `timestamp` (string): Timestamp to analyze
167+
- `timezone` (string, optional): Timezone for context (default: "UTC")
168+
169+
**Example:**
170+
```
171+
Is March 15, 2024 2:30 PM a business day?
172+
```
173+
174+
### `adjust_timestamp`
175+
Add or subtract a duration from a timestamp.
176+
177+
**Parameters:**
178+
- `timestamp` (string): Base timestamp
179+
- `adjustment` (string): Adjustment to apply (e.g., "+1 day", "-2 hours")
180+
- `timezone` (string, optional): Timezone for calculation (default: "UTC")
181+
182+
**Example:**
183+
```
184+
What date is 30 days after March 1, 2024?
185+
```
186+
187+
## Testing the Server
188+
189+
Try these example prompts with your AI agent:
190+
191+
### Basic Operations
192+
- "What time is it right now?"
193+
- "What's the current time in Tokyo?"
194+
- "Convert 3:30 PM EST to Pacific Time"
195+
196+
### Date Calculations
197+
- "How many days until Christmas?"
198+
- "What day of the week was January 1st, 2000?"
199+
- "Add 45 days to March 15, 2024"
200+
201+
### Complex Scenarios
202+
- "I have a flight departing Los Angeles at 11:30 PM on Friday. If the flight is 14 hours long, what time will I arrive in Tokyo local time?"
203+
- "Calculate work hours in February 2024, assuming 8-hour workdays Monday through Friday"
204+
205+
## Development
8206

9207
### Prerequisites
10208

11209
- Python 3.12+
12-
- [Poetry](https://python-poetry.org/) (1.2+ recommended) for dependency management.
210+
- Poetry for dependency management
211+
- Docker (optional, for containerized deployment)
13212

14-
### Installation
213+
### Setup
15214

16-
1. **Clone the repository:**
17-
```bash
18-
git clone https://github.com/your-username/temporal-awareness-mcp.git
19-
cd temporal-awareness-mcp
20-
```
215+
```bash
216+
# Clone and install
217+
git clone <repository-url>
218+
cd temporal-awareness-mcp
219+
poetry install
21220

22-
2. **Install dependencies:**
23-
Poetry will create a dedicated virtual environment and install all necessary packages from the `poetry.lock` file, ensuring a consistent and reliable setup.
24-
```bash
25-
poetry install
26-
```
221+
# Run tests
222+
poetry run pytest
223+
```
27224

28-
## 🏃‍♀️ Running the Server
225+
## Deployment
29226

30-
To run the development server, use the following command. The `--reload` flag enables hot-reloading, which means the server will automatically restart whenever you save a change to the code.
227+
### Docker
31228

32229
```bash
33-
poetry run python -m uvicorn temporal_awareness_mcp.main:mcp --reload
34-
```
230+
# Build and run
231+
docker-compose up -d --build
232+
233+
# Check logs
234+
docker-compose logs temporal-awareness-mcp-server
235+
236+
# Stop
237+
docker-compose down
238+
```
239+
240+
### Environment Variables
241+
242+
For production deployment, you can configure:
243+
244+
- `HOST`: Server host (default: "0.0.0.0")
245+
- `PORT`: Server port (default: 8000)
246+
247+
## License
248+
249+
MIT License

‎docker-compose.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
version: "3.8"
2+
3+
services:
4+
server:
5+
build: .
6+
container_name: temporal-awareness-mcp-server
7+
ports:
8+
- "8000:8000"
9+
restart: unless-stopped

0 commit comments

Comments
 (0)