mcp-date-server 0.1.0
An example Model Context Protocol (MCP) server exposing a getTodaysDate tool.
License: MIT
Requires Python: >=3.9
Keywords: mcp, model-context-protocol, tools, date

# mcp-date-server

An example Python package that implements a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server with a single tool:

- `getTodaysDate`: returns today's date in ISO format (YYYY-MM-DD).

This server is implemented using the Python `mcp` SDK and is suitable for use with MCP-compatible clients.

## Project Structure

```text
mcp-date-server/
├── pyproject.toml
├── README.md
└── src/
    └── mcp_date_server/
        ├── __init__.py
        └── server.py
```

- `pyproject.toml`: build configuration and package metadata.
- `src/mcp_date_server/server.py`: MCP server implementation and `getTodaysDate` tool.

## Installation (from source)

1. Clone or copy this project into a directory, then from the project root run:

   ```bash
   python -m venv .venv
   .venv\Scripts\activate  # Windows
   # source .venv/bin/activate  # Linux/macOS

   pip install --upgrade pip
   pip install .
   ```

2. This installs the `mcp-date-server` console script into your environment.

You can also build a wheel and install it:

```bash
pip install build
python -m build
pip install dist/mcp_date_server-0.1.0-py3-none-any.whl
```

## Usage

Once installed in an activated virtual environment, you can run the MCP server via the console entry point:

```bash
mcp-date-server
```

This starts an MCP server on stdio for an MCP client to connect to.

### MCP Client Configuration Example

How you configure this server depends on your MCP-compatible client. As a conceptual example (not specific to any one client), you might register the server with a command like:

```jsonc
{
  "name": "mcp-date-server",
  "command": "mcp-date-server",
  "args": []
}
```

Refer to your MCP client documentation for the exact configuration format.

## The `getTodaysDate` Tool

The MCP tool is defined in `src/mcp_date_server/server.py`:

- Name: `getTodaysDate`
- Description: Returns today's date in ISO format `YYYY-MM-DD`.
- Return type: `string`.

Example result value:

```json
"2026-01-28"
```

## Publishing to PyPI

1. Ensure you have an up-to-date `build` and `twine`:

   ```bash
   pip install --upgrade build twine
   ```

2. Build the distribution artifacts:

   ```bash
   python -m build
   # Outputs files under the dist/ directory
   ```

3. Upload to PyPI (or TestPyPI first):

   ```bash
   # For TestPyPI
   twine upload --repository testpypi dist/*

   # For real PyPI
   twine upload dist/*
   ```

4. After publishing, users can install it with:

   ```bash
   pip install mcp-date-server
   ```

## Requirements

- Python 3.9+
- The `mcp` Python package (installed automatically via `pyproject.toml`).

## Running Locally Without Installing

For quick local testing without installing as a package:

```bash
python -m venv .venv
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # Linux/macOS

pip install -e .

mcp-date-server
```

This installs the package in editable mode and exposes the `mcp-date-server` entry point for development.