# Linera Counter MCP Server Demo

This demo showcases an MCP (Model Context Protocol) server that connects to a counter application running on the Linera blockchain via GraphQL. The MCP server enables Claude to interact with the on-chain counter through natural language commands.

## Architecture Overview

- **Linera Counter Application**: A counter application deployed on Linera that exposes GraphQL endpoints
- **Apollo MCP Server**: Acts as a bridge between Claude and the Linera GraphQL API
- **Claude Desktop**: MCP client that can query and mutate the counter through natural language

## Prerequisites

1. **Linera CLI**: Ensure you have the `linera` binary installed and available in your PATH

2. **Rust**: Required to build and run the Apollo MCP server
   ```bash
   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   ```

3. **Claude Desktop**: Install Claude Desktop app to connect to the MCP server

## Setup Instructions

### Step 1: Install Apollo MCP Server

1. Clone the Apollo MCP Server repository:
   ```bash
   git clone https://github.com/apollographql/apollo-mcp-server.git
   cd apollo-mcp-server
   ```

2. Build the MCP server:
   ```bash
   cargo build --release
   ```

### Step 2: Deploy the Counter Application on Linera

1. Start your Linera validator and ensure you have a default chain configured:
   ```bash
   linera wallet show
   ```

2. Deploy the counter application using the `linera` CLI with an initial value:
   ```bash
   linera project publish-and-create examples/counter --json-argument "0"
   ```
   
   This command will:
   - Build the counter application bytecode
   - Publish it to your chain
   - Create an application instance initialized with counter value 0
   - Return the application ID (note this for the next step)

3. Start the Linera service with GraphQL enabled:
   ```bash
   linera service --port 8080
   ```
   
   This starts the Linera node service with GraphQL endpoint at `http://localhost:8080`

### Step 3: Launch the Apollo MCP Server

1. From the apollo-mcp-server directory, run the MCP server with your specific chain ID and application ID:
   ```bash
   cargo run -- \
     --schema ../counter.graphql \
     --endpoint http://localhost:8080/chains/<YOUR_CHAIN_ID>/applications/<YOUR_APPLICATION_ID> \
     --allow-mutations all \
     --introspection \
     --http-address 127.0.0.1
   ```

   Replace:
   - `<YOUR_CHAIN_ID>` with your actual chain ID (from `linera wallet show`)
   - `<YOUR_APPLICATION_ID>` with the application ID returned from Step 2

   **Example**:
   ```bash
   cargo run -- \
     --schema ../counter.graphql \
     --endpoint http://localhost:8080/chains/e9baa1f0e0a3b8c61b13a61a106e446bcffaea77fa13a8d2164b681c37aa34e1/applications/2b1a0df8868206a4b7d6c2fdda911e4355d6c0115b896d4947ef8e535ee3c6b8 \
     --allow-mutations all \
     --introspection \
     --http-address 127.0.0.1
   ```

   The MCP server will:
   - Connect to the Linera GraphQL endpoint
   - Introspect the counter application schema
   - Expose counter operations as MCP tools
   - Listen for MCP client connections on stdio

### Step 4: Connect Claude Desktop

1. Configure Claude Desktop to connect to the MCP server by adding this to your Claude Desktop configuration:

   **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

   ```json
   {
     "mcpServers": {
       "linera-counter": {
         "command": "cargo",
         "args": [
           "run",
           "--manifest-path",
           "/path/to/apollo-mcp-server/Cargo.toml",
           "--",
           "--schema",
           "/path/to/claude-demo/counter.graphql",
           "--endpoint",
           "http://localhost:8080/chains/<YOUR_CHAIN_ID>/applications/<YOUR_APPLICATION_ID>",
           "--allow-mutations",
           "all",
           "--introspection",
           "--http-address",
           "127.0.0.1"
         ],
         "env": {}
       }
     }
   }
   ```

   **Note**: Replace `/path/to/apollo-mcp-server/` with the actual path to where you cloned the Apollo MCP Server repository, and replace the chain/application IDs with your actual values.

2. Restart Claude Desktop to load the MCP server configuration.

## Available Tools

The MCP server automatically discovers and exposes the following tools based on the counter GraphQL schema:

### Query Tools
- **`value`**: Query the current counter value
  - Returns the current integer value of the counter

### Mutation Tools  
- **`increment`**: Increment the counter by a specified value
  - Parameters: `value` (Int!) - The amount to increment by
  - Returns: Array of integers representing the operation result

## Example Claude Session

Once everything is set up, you can interact with the Linera counter through Claude:

---

**You**: "What's the current value of the counter?"

**Claude**: I'll check the current counter value for you.

*[Uses the `value` query tool]*

The current counter value is 0.

---

**You**: "Increment the counter by 5"

**Claude**: I'll increment the counter by 5 for you.

*[Uses the `increment` mutation tool with value: 5]*

Successfully incremented the counter by 5. The operation completed and returned [5].

---

**You**: "What's the counter value now?"

**Claude**: Let me check the updated counter value.

*[Uses the `value` query tool]*

The counter value is now 5.

---

**You**: "Add 10 more to the counter"

**Claude**: I'll add 10 to the counter.

*[Uses the `increment` mutation tool with value: 10]*

Successfully incremented the counter by 10. The operation returned [15], and the counter value is now 15.

---

**You**: "Can you increment it by 3 and then tell me the new value?"

**Claude**: I'll increment the counter by 3 and then check the new value for you.

*[Uses the `increment` mutation tool with value: 3]*

*[Uses the `value` query tool]*

I've successfully incremented the counter by 3. The counter value is now 18.

---

## Troubleshooting

### Common Issues

1. **Connection Refused**: Ensure the Linera service is running on the correct port
   ```bash
   linera service --port 8080
   ```

2. **Invalid Chain/Application ID**: Use `linera wallet show` to verify your chain ID and ensure you're using the correct application ID from deployment

3. **MCP Server Not Found**: Check that the file paths in the Claude Desktop configuration are correct and that Rust/Cargo are properly installed

4. **GraphQL Schema Errors**: Ensure the counter application is deployed and the Linera service can access it

### Debugging Commands

Check if the Linera service is accessible:
```bash
curl http://localhost:8080/
```

Query the counter directly via GraphQL:
```bash
curl -X POST http://localhost:8080/chains/<CHAIN_ID>/applications/<APP_ID> \
  -H "Content-Type: application/json" \
  -d '{"query": "{ value }"}'
```

List your deployed applications:
```bash
linera wallet show
```

Test the MCP server connection:
```bash
cd apollo-mcp-server
cargo run -- \
  --endpoint http://localhost:8080/chains/<YOUR_CHAIN_ID>/applications/<YOUR_APPLICATION_ID> \
  --allow-mutations all \
  --introspection \
  --http-address 127.0.0.1
```

## Next Steps

- Explore other Linera example applications that could be exposed via MCP
- Try building custom applications with more complex GraphQL schemas
- Experiment with different MCP client integrations beyond Claude Desktop
- Build multi-chain applications that can be federated through the MCP server

For more information about Linera development, see the [Linera Documentation](https://linera.dev/).

For more about Apollo MCP Server, see the [Apollo MCP Server repository](https://github.com/apollographql/apollo-mcp-server).