# 🕰️ OpenTimeStamps MCP Server

A Model Context Protocol (MCP) server that enables AI models to interact with OpenTimeStamps, allowing them to timestamp
files and verify proofs on the Bitcoin blockchain.

Trustless timestamping for the AI age.

[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-Protocol-blue?style=flat-square)](https://github.com/modelcontextprotocol/typescript-sdk)
[![OpenTimeStamps](https://img.shields.io/badge/OpenTimeStamps-Proof-orange?style=flat-square)](https://opentimestamps.org/)

## 🚀 Features

- 🔢 Calculate hash values (SHA256, SHA1, RIPEMD160)
- ⏰ Submit hashes for timestamping via OpenTimeStamps calendars
- 📁 Load and parse OTS proof files
- 📊 Display detailed information about OTS proofs
- ⬆️ Upgrade incomplete OTS proofs
- ✅ Verify OTS proofs against original data or hashes
- 🌐 Server-Sent Events (SSE) support for web integration
- 🔌 MCP-compliant API for AI integration

## 📋 Prerequisites

- Node.js 18+

## 🛠️ Installation

### Installing via Smithery (Coming Soon)

To install OpenTimeStamps MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/):

```bash
npx -y @smithery/cli install @fmar/opentimestamps-mcp --client claude
```

### Manual Installation

1. Clone the repository:

```bash
git clone https://github.com/fmargarita/opentimestamps-mcp
cd opentimestamps-mcp
```

2. Install dependencies:

```bash
npm install
```

3. Build the project:

```bash
npm run build
```

4. Create a `.env` file (optional):

You can copy `.env.example` and modify as needed:

```bash
cp .env.example .env
```

## 🔧 Setup with Claude Desktop

To use this MCP server with Claude Desktop, add the following to your Claude Desktop configuration file:

### macOS
```bash
# Edit the configuration file
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

### Windows
```bash
# Edit the configuration file
notepad %APPDATA%\Claude\claude_desktop_config.json
```

### Configuration
Add this configuration to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "opentimestamps": {
      "command": "node",
      "args": ["/absolute/path/to/opentimestamps-mcp/build/cli.js"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}
```

**Important**: Replace `/absolute/path/to/opentimestamps-mcp/` with the actual path where you cloned this repository.

After updating the configuration:

1. Restart Claude Desktop
2. You should see the OpenTimeStamps tools available in your conversation

## 🔧 Setup with Goose

For Goose AI assistant, add this to your `config.yaml`:

```yaml
mcp:
  servers:
    opentimestamps:
      command: node
      args:
        - /absolute/path/to/opentimestamps-mcp/build/cli.js
      env:
        LOG_LEVEL: info
```

## 🚦 Usage

### Starting the Server

```bash
# Development mode with hot reload
npm run dev

# Production mode
npm start
```

### Available Tools

#### `calculate_hash`

Calculate the hash of data using the specified algorithm.

Example input:

```json
{
  "data": "Hello, OpenTimeStamps!",
  "algorithm": "sha256"
}
```

#### `stamp_hash`

Submit a hash for timestamping using OpenTimeStamps calendar servers.

Example input:

```json
{
  "hash": "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3",
  "algorithm": "sha256"
}
```

#### `load_proof`

Load an OTS proof from hex data or file path.

Example input:

```json
{
  "otsData": "004f70656e54696d657374616d7073000050726f6f66...",
  "isFilePath": false
}
```

#### `get_proof_info`

Display detailed information about an OTS proof.

Example input:

```json
{
  "otsData": "004f70656e54696d657374616d7073000050726f6f66..."
}
```

#### `upgrade_proof`

Upgrade an incomplete OTS proof by fetching missing attestations.

Example input:

```json
{
  "otsData": "004f70656e54696d657374616d7073000050726f6f66..."
}
```

#### `verify_proof`

Verify an OTS proof against original data or hash.

Example input:

```json
{
  "otsData": "004f70656e54696d657374616d7073000050726f6f66...",
  "originalData": "Hello, OpenTimeStamps!",
  "algorithm": "sha256"
}
```

## 🔧 Development

### Project Structure

```text
opentimestamps-mcp/
├── src/
│   ├── index.ts        # Main server entry point
│   ├── ots-client.ts   # OpenTimeStamps client implementation
│   ├── stdio_server.ts # STDIO transport server
│   ├── sse_server.ts   # SSE transport server
│   ├── types.ts        # TypeScript type definitions
│   ├── types/          # Type declarations
│   └── utils/          # Utility functions
├── .env.example        # Environment configuration template
├── claude_desktop_config.json # Claude Desktop config example
└── tsconfig.json       # TypeScript configuration
```

### Running Tests

```bash
npm test
```

## 📚 Examples

### Basic Workflow

1. **Calculate a hash of your data:**
   ```
   Use the calculate_hash tool with your text or data
   ```

2. **Submit for timestamping:**
   ```
   Use the stamp_hash tool with the resulting hash
   ```

3. **Check the proof:**
   ```
   Use get_proof_info to see the attestation details
   ```

4. **Upgrade proof (after ~10 minutes):**
   ```
   Use upgrade_proof to get Bitcoin confirmations
   ```

5. **Verify the proof:**
   ```
   Use verify_proof with your original data and the proof
   ```

### Sample Conversation with Claude

```
User: "Please calculate the SHA256 hash of 'Hello World'"

Claude will use: calculate_hash
Input: {"data": "Hello World", "algorithm": "sha256"}

User: "Now timestamp that hash"

Claude will use: stamp_hash  
Input: {"hash": "a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e", "algorithm": "sha256"}

User: "Show me the proof information"

Claude will use: get_proof_info
Input: {"otsData": "004f70656e54696d657..."}
```

## 🔒 Privacy & Security

OpenTimeStamps provides cryptographic proof of existence without revealing file contents:

- **Privacy**: Only file hashes are submitted to calendar servers, never the actual data
- **Trustless**: Verification is done against the Bitcoin blockchain, not trusted third parties
- **Immutable**: Once timestamped on Bitcoin, proofs cannot be altered or removed
- **Verifiable**: Anyone can independently verify timestamps using the Bitcoin blockchain

## ⚙️ Configuration

All configuration is optional and handled through environment variables:

- `OTS_CALENDAR_SERVERS`: Custom calendar servers (defaults to standard OTS servers)
- `BITCOIN_RPC_*`: Bitcoin node connection for local verification (optional)
- `SERVER_MODE`: Choose between `stdio` (default) or `sse` transport
- `PORT`: HTTP port for SSE mode (default: 3000)

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📜 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🔗 Resources

- [OpenTimeStamps Website](https://opentimestamps.org/)
- [OpenTimeStamps Python Client](https://github.com/opentimestamps/opentimestamps-client)
- [OpenTimeStamps JavaScript Library](https://github.com/opentimestamps/javascript-opentimestamps)
- [Model Context Protocol](https://modelcontextprotocol.io/introduction)
- [Visual testing tool for MCP servers](https://github.com/modelcontextprotocol/inspector)
- [Awesome MCP Servers](https://github.com/punkpeye/awesome-mcp-servers)

## 🚀 Getting Started

The fastest way to test the server:

1. **Calculate a hash:**
   ```
   "Calculate the SHA256 hash of 'Hello World'"
   ```

2. **Timestamp the hash:**
   ```
   "Timestamp that hash using OpenTimeStamps"
   ```

3. **Verify later:**
   ```
   "Verify the proof against the original text 'Hello World'"
   ```

---

<p align="center">
  Made with ❤️ for timestamping and blockchain verification
</p>