# CaesarCipher

CaesarCipher is a small Microsoft Foundry prompt-agent sample that uses an
Azure Function app as a remote MCP tool.

The Foundry agent receives the user's request, calls the MCP tool exposed by the
Function app, and returns the tool result. The Caesar transformation is owned by
the Function app, not by the prompt agent.

> [!WARNING]
> This is an experimental learning project and should not be considered
> production-ready.

## What It Does

The agent handles requests such as:

- "Please encode the message: Hello"
- "Encode the following plaintext: Attack at dawn"

The prompt in `prompt.md` instructs the Foundry agent to call the MCP tool named
`caesar-cipher-function`. The tool accepts a single `plaintext` argument and
returns the encoded text.

## Architecture

```text
Foundry prompt agent
  -> remote MCP server connection
  -> Azure Functions MCP webhook
  -> caesar-cipher-function
  -> src/azure_functions/caesar_ciper.py
```

The Azure Functions MCP endpoint is:

```text
https://{function-app-name}.azurewebsites.net/runtime/webhooks/mcp
```

Do not configure Foundry with only the Function App base URL. The base URL
returns a normal web response, not MCP JSON-RPC messages.

## Foundry Setup

Create and configure the agent in [Microsoft Foundry](https://ai.azure.com/):

1. Create or open a Foundry project.
2. Deploy a chat model in that project.
3. Create a prompt agent named `caesar-cipher`.
4. Paste the contents of `prompt.md` into the agent instructions.
5. Add a remote MCP server tool connection.
6. Set the remote MCP server endpoint to
   `https://{function-app-name}.azurewebsites.net/runtime/webhooks/mcp`.
7. Set authentication to unauthenticated for early testing.
8. Configure the allowed tool as `caesar-cipher-function`.
9. Save and test the agent in Foundry Chat.

The tool call should appear in Foundry Chat as a call to
`caesar-cipher-function` with a `plaintext` argument.

## Azure Function App

The deployable Azure Function app files live in `src/azure_functions/`.

For zip deployment, zip the contents of this directory so these files are at the
zip root:

```text
function_app.py
caesar_ciper.py
host.json
requirements.txt
```

`function_app.py` uses the Azure Functions Python v2 programming model and the
`@app.mcp_tool_trigger` decorator to expose `caesar-cipher-function`.

`host.json` configures the Azure Functions MCP extension and currently allows
anonymous access to the MCP webhook for testing. Add authentication before using
this pattern outside a learning environment.

## Local MCP Smoke Test

After deploying the Function app, test the MCP server directly before testing
through Foundry:

```powershell
.\scripts\test-mcp-endpoint.ps1 -Endpoint "https://{function-app-name}.azurewebsites.net/runtime/webhooks/mcp" -Plaintext "Hello"
```

For the current sample deployment, the script defaults to the known MCP endpoint,
so this is enough:

```powershell
.\scripts\test-mcp-endpoint.ps1 -Plaintext "Hello"
```

A healthy endpoint lists `caesar-cipher-function` from `tools/list` and returns
the encoded text from `tools/call`.

## Local Setup

Create the virtual environment and install the project with development
dependencies:

```powershell
.\scripts\setup-dev.ps1
```

The setup script expects Python 3.11 at the path configured in
`scripts/setup-dev.ps1`.

## Foundry CLI

The repository also includes a small local CLI for calling the Foundry prompt
agent after the agent is available:

```powershell
.\.venv\Scripts\python.exe -m caesar_cipher "Please encode the message: Hello"
```

The command calls the live Foundry endpoint and may incur Azure or model usage
costs.

The current local CLI is configured for:

```text
agent name: caesar-cipher
agent version: 1
```

If the project endpoint, agent name, or agent version changes, update
`src/caesar_cipher/cli.py`.

## Development Checks

Run formatting, linting, type checking, and tests:

```powershell
.\scripts\check.ps1
```

This runs:

- `ruff format .`
- `ruff check .`
- `pyright`
- `pytest`

## Project Structure

```text
src/azure_functions/
  function_app.py    Azure Functions MCP tool trigger
  caesar_ciper.py    Caesar transformation implementation
  host.json          Azure Functions host and MCP extension settings
  requirements.txt   Function app deployment dependencies

src/caesar_cipher/
  __main__.py        Package entry point for python -m caesar_cipher
  cli.py             Foundry client setup and command-line entry point

scripts/
  setup-dev.ps1
  check.ps1
  test-mcp-endpoint.ps1
  test_mcp_endpoint.py

tests/
  test_caesar_ciper.py
  test_function_app.py
  test_smoke.py

prompt.md           Prompt instructions pasted into the Foundry agent
```

## Notes

This project is a Foundry learning exercise, not a production cryptography
system. A Caesar cipher is a historical substitution cipher and is not secure
for protecting sensitive information.

Do not include secrets or sensitive personal data in test prompts. The local CLI
calls the remote Foundry agent and sends prompts to the configured Foundry
project.

## Third-Party Notices

This project has direct runtime dependencies on third-party Python packages,
including `azure-ai-projects`, `azure-functions`, `azure-identity`, and `httpx`.
See each package's PyPI license metadata for full license and notice terms.

## License

GNU General Public License v3.0. See the `LICENSE` file for details.