> [!IMPORTANT]
> **This repository is archived and read-only.**
>
> A native MCP feature was added in Harper v5.1. See the [MCP overview](https://docs.harper.fast/reference/v5/mcp/overview) for more information.
> It is pinned to **HarperDB v4** and is preserved for reference.
> It is **not** kept in sync with current releases and may not be supported in latest Harper versions.
>
> For up-to-date guides and reference docs, see the [Harper docs](https://docs.harper.fast) and join our [Discord](https://harper.fast/discord).

# Harper MCP Server

A server implementation of the [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol), designed to expose data in HarperDB as structured "Resources" accessible via standardized JSON-RPC calls.

> **Note:** Requires HarperDB version 4.5.10 or later.

## What is Harper
[Harper](https://www.harpersystems.dev/) is a Composable Application Platform that merges database, cache, app logic, and messaging into a single runtime. Components like this plug directly into Harper, letting you build and scale distributed services fast, without managing separate systems. Built for geo-distributed apps with low latency and high uptime by default.

---

## Features

- MCP-compatible API server for Harper
- Predefined static capabilities endpoint (`/capabilities.json`)
- Provides read-only access to data from Harper tables and custom resources
- Supports filtering data in Harper tables using query parameters
- Handles pagination (limit, start) for table data retrieval
- Provides standardized error responses

---

## Getting Started

### Prerequisites

- [Harper](https://docs.harperdb.io/docs/deployments/install-harperdb/) stack installed globally.
- Ensure HarperDB v4.5.10 or later is configured and running with necessary databases and schemas.
- Environment variable `HOST` should be set to the base URL of your server. This is used to construct resource URIs.

### Deploying to Harper

The Harper `mcp-server` is published to NPM and can be installed using [Harper's Operation API](https://docs.harperdb.io/docs/developers/operations-api/components).

i.e.

`POST https://harper-server.com:9925`

```json
{
	"operation": "deploy_component",
	"package": "@harperdb/mcp-server@1.0.0"
}
```

## Security & Authentication

Harper employs role-based, attribute-level security to ensure users access only authorized data. Requests to the server are authenticated using HarperDB's built-in authentication mechanisms, which include Basic Auth, JWT, and mTLS.
See [Harper Security Docs](https://docs.harperdb.io/docs/developers/security/) for more details.

## API

### MCP Methods

The server implements the following MCP methods:

- **`resources/list`**: Lists all available resources (HarperDB tables and custom resources).
- **`resources/read`**: Retrieves data for a specific resource based on its URI.

A single endpoint, `/mcp` handles all requests. The server uses JSON-RPC 2.0 for communication.

- **Request Format**: All requests are sent as JSON-RPC 2.0 formatted JSON objects.
- **Response Format**: The server responds with JSON-RPC 2.0 formatted JSON objects.
- **Error Handling**: The server returns standardized error responses.

### Resource URIs

- **Tables:** Resources representing HarperDB tables are accessed via URIs like:

  ```
  {HOST}/{table_name}
  ```

  - Example: `http://localhost:9925/my_table`

- **Table Rows:** Individual rows within a table can be accessed using the primary key:

  ```
  {HOST}/{table_name}/{primary_key_value}
  ```

  - Example: `http://localhost:9925/my_table/123` (where 123 is the primary key value)

- **Custom Resources:** Custom resources are accessed via URIs defined by their registered path:

  ```
  {HOST}/{path}/{resource_name}
  ```

  - Example: `http://localhost:9925/custom/my_resource`

## Usage

### 1. Listing Resources

POST `/mcp`

Sample Request:

```json
{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "resources/list"
}
```

Sample Response:

```json
{
	"jsonrpc": "2.0",
	"id": 1,
	"result": {
		"resources": [
			{
				"uri": "http://localhost:9926/CustomerOrders",
				"name": "CustomerOrders",
				"description": "CustomerOrders table with attributes: id (PK - Int), customerId (string), customer (Relationship from customerId - Customers), itemSku (String), item (Relationship from itemSku - Items), subTotal (Float), orderTotal (Float), date (DateTime). Results can be filtered with optional query parameters.",
				"mimeType": "application/json"
			},
			{
				"uri": "http://localhost:9926/Customers",
				"name": "Customers",
				"description": "Customers table with attributes: id (PK - Int), email (String), phoneNumber (String), customerName (String), country (String), orders (Relationship to customerId - array). Results can be filtered with optional query parameters.",
				"mimeType": "application/json"
			},
			{
				"uri": "http://localhost:9926/Items",
				"name": "Items",
				"description": "Items table with attributes: sku (PK - String), itemName (String), itemDescription (String), unitPrice (Int). Results can be filtered with optional query parameters.",
				"mimeType": "application/json"
			},
			{
				"uri": "http://localhost:9926/TestCustomer",
				"name": "TestCustomer",
				"description": "Customers table with attributes: id (PK - Int), email (String), phoneNumber (String), customerName (String), country (String), orders (Relationship to customerId - array). Results can be filtered with optional query parameters.",
				"mimeType": "application/json"
			},
			{
				"uri": "http://localhost:9926/api/test",
				"name": "test",
				"description": "REST Resource.",
				"mimeType": "application/json"
			}
		]
	}
}
```

### 2. Get resources data

POST `/mcp`

Sample Request:

```json
{
	"jsonrpc": "2.0",
	"id": 2,
	"method": "resources/read",
	"params": {
		"uri": "http://localhost:9926/Customers"
	}
}
```

Sample Response:

```json
{
	"jsonrpc": "2.0",
	"id": 2,
	"result": {
		"contents": [
			{
				"uri": "http://localhost:9926/Customers/11",
				"mimeType": "application/json",
				"text": "{\"id\":11,\"email\":\"kelly.williams@example.com\",\"phoneNumber\":\"214-555-1234\",\"customerName\":\"Kelly Williams\",\"country\":\"USA\"}"
			},
			{
				"uri": "http://localhost:9926/Customers/12",
				"mimeType": "application/json",
				"text": "{\"id\":12,\"email\":\"liam.martinez@example.com\",\"phoneNumber\":\"972-555-5678\",\"customerName\":\"Liam Martinez\",\"country\":\"Canada\"}"
			},
			{
				"uri": "http://localhost:9926/Customers/13",
				"mimeType": "application/json",
				"text": "{\"id\":13,\"email\":\"mia.anderson@example.com\",\"phoneNumber\":\"469-555-9012\",\"customerName\":\"Mia Anderson\",\"country\":\"UK\"}"
			},
			{
				"uri": "http://localhost:9926/Customers/14",
				"mimeType": "application/json",
				"text": "{\"id\":14,\"email\":\"noah.thomas@example.com\",\"phoneNumber\":\"817-555-3456\",\"customerName\":\"Noah Thomas\",\"country\":\"Australia\"}"
			},
			{
				"uri": "http://localhost:9926/Customers/15",
				"mimeType": "application/json",
				"text": "{\"id\":15,\"email\":\"olivia.jackson@example.com\",\"phoneNumber\":\"682-555-7890\",\"customerName\":\"Olivia Jackson\",\"country\":\"Germany\"}"
			},
			{
				"uri": "http://localhost:9926/Customers/16",
				"mimeType": "application/json",
				"text": "{\"id\":16,\"email\":\"owen.white@example.com\",\"phoneNumber\":\"214-555-2345\",\"customerName\":\"Owen White\",\"country\":\"France\"}"
			},
			{
				"uri": "http://localhost:9926/Customers/17",
				"mimeType": "application/json",
				"text": "{\"id\":17,\"email\":\"sophia.harris@example.com\",\"phoneNumber\":\"972-555-6789\",\"customerName\":\"Sophia Harris\",\"country\":\"Japan\"}"
			}
		]
	}
}
```

### Querying Tables

When retrieving data from tables using `resources/read`, you can use optional query parameters in the URI to filter data.

- **Filtering:** Use `attribute=value` pairs to filter based on column values. The comparator is always "equals".
  - Example: `http://localhost:9925/my_table?name=John&city=NewYork`
- **Pagination:** Use `limit` and `start` parameters for pagination.
  - `limit`: Maximum number of results to return.
  - `start`: Offset to start returning results from.
  - Example: `http://localhost:9925/my_table?limit=10&start=20`

### Error Responses

The server returns standardized JSON-RPC error responses:

```json
{
	"jsonrpc": "2.0",
	"id": 2,
	"error": {
		"code": -32602,
		"message": "Invalid params."
	}
}
```

Error Codes:

- `-32601`: Method not found.
- `-32602`: Invalid params.
- `-32603`: Internal server error.