# Sloan / Guides Documentation – TypeScript

## Included Files
1. sloan/guides/clickhouse-chat.mdx
2. sloan/guides/clickhouse-proj.mdx
3. sloan/guides/from-template.mdx

## clickhouse-chat

Source: sloan/guides/clickhouse-chat.mdx

## Quickstart: AI Chat with ClickHouse
*Use your LLM client to explore your ClickHouse with Sloan MCP tools.*

This will walk you through using Sloan CLI to connect Sloan MCP tools to your ClickHouse database, allowing you to chat with your data in your client of choice. We'll use the ClickHouse Playground as our example database, but you can use any ClickHouse database.

- **OS**: macOS or Linux (WSL supported for Windows)
- **Node**: [version 20+](https://nodejs.org/en/download) (LTS recommended)
- **Client**: [Cursor](https://www.cursor.com/) or [Claude Desktop](https://claude.ai/download) or [Windsurf](https://windsurf.ai/download). For this particular use-case, we recommend Claude Desktop.

### Install Sloan CLI

```bash filename="Terminal" copy
bash -i <(curl -fsSL https://fiveonefour.com/install.sh) sloan
```

### Configure your Sloan MCP

```bash filename="Terminal" copy
sloan connect clickhouse --connection-string "https://explorer:@play.clickhouse.com:443/?database=default" --mcp cursor-project
```

You need a ClickHouse connection URL. Format looks like this:

```
http://username:password@host:port/?database=database_name
```

Want to test without your own ClickHouse? Use the [ClickHouse Playground](https://clickhouse.com/docs/getting-started/playground) with the connection string above. It has sample datasets (read-only) you can experiment with.

```txt copy
https://explorer:@play.clickhouse.com:443/?database=default
```

    <Tabs.Tab>
      1. Log into your [ClickHouse Cloud console](https://clickhouse.cloud/)
      2. Go to your service details page
      3. Find "Connect" or "Connection Details" section
      4. Copy the HTTPS endpoint and your username/password
    </Tabs.Tab>
    <Tabs.Tab>
      - Check your ClickHouse config file (usually `/etc/clickhouse-server/config.xml`)
      - Look for `<http_port>` (default: 8123) and `<https_port>` (default: 8443)
      - Check users config in `/etc/clickhouse-server/users.xml` or users.d/ directory
      - Default user is often `default` with no password
    </Tabs.Tab>
    <Tabs.Tab>
      - Check your docker-compose.yml or docker run command for environment variables
      - Look for `CLICKHOUSE_USER`, `CLICKHOUSE_PASSWORD`, `CLICKHOUSE_DB`
      - Default is usually `http://default:@localhost:8123/?database=default`
    </Tabs.Tab>

- **Can't connect?** Try `curl http://your-host:8123/ping` to test connectivity
- **Authentication failed?** Verify username/password with `clickhouse-client --user=username --password=password`
- **Database not found?** Run `SHOW DATABASES` to see available databases
- **Permission denied?** Check user permissions with `SHOW GRANTS FOR username`

**Still stuck?** Check the [ClickHouse documentation](https://clickhouse.com/docs/en/getting-started/install) for your specific deployment method.

### Chat

Open your Claude Desktop client. We recommend starting the chat with a context setting question like "tell me about the data I have available to me in ClickHouse".

You can check that the MCP is correctly configured by looking at `claude > settings > developer > sloan`. It should say "running".

You can can also look at `search and tools` beneath the chat window, you should see `sloan` in the list of MCPs—if you click into it, you should see the tools that are enabled.

### What's next?

Try [creating a Moose Project from your ClickHouse database](https://docs.fiveonefour.com/sloan/quickstart/clickhouse-proj). That way, you can use Sloan MCP tools to create new primitives, like ingestion paths, data models, egress APIs, and more!

Or try [deploying your project to Boreal](https://www.fiveonefour.com/boreal), our hosting platform for Moose projects.

## Other Quickstart Guides

---

## clickhouse-proj

Source: sloan/guides/clickhouse-proj.mdx

## Quickstart: AI analytics engineering from your ClickHouse
*Generate a local OLAP project from your ClickHouse deployment; Sloan MCP pre-configured for analytics engineering.*

This will walk you through creating a new local Moose project reflecting the structure of your ClickHouse database. It will allow you to add data to your local dev environment from your remote ClickHouse database, and use Sloan MCP tools to enrich your project with metadata, or create new Moose primitives that you can use in your project (e.g.egress APIs). We'll use the ClickHouse Playground as our example database, but you can use any ClickHouse database.

- **OS**: macOS or Linux (WSL supported for Windows)
- **Docker Desktop/Engine**: [24.0.0+](https://docs.docker.com/get-started/get-docker/)
- **Node**: [version 20+](https://nodejs.org/en/download) (LTS recommended)
- **Anthropic API Key**: [Get one here](https://docs.anthropic.com/en/docs/initial-setup)
- **Client**: [Cursor](https://www.cursor.com/) or [Claude Desktop](https://claude.ai/download) or [Windsurf](https://windsurf.ai/download). For this particular use-case, we recommend Claude Desktop.

### Install Moose and Sloan CLIs

```bash filename="Terminal" copy
bash -i <(curl -fsSL https://fiveonefour.com/install.sh) moose,sloan
```

We'll be using generative MCP tools here, so make sure you add your Anthropic API key in install. If you installed without adding it, you can add it later with `sloan config keys anthropic <your-api-key>`. If you need to create one, see: https://docs.anthropic.com/en/docs/initial-setup.

### Create a new Moose project from your ClickHouse database

```bash filename="Terminal" copy
sloan init my_project_name --from-remote 'https://explorer:@play.clickhouse.com:443/?database=default' --language python --mcp cursor-project
```

Want to test without your own ClickHouse? Use the [ClickHouse Playground](https://clickhouse.com/docs/getting-started/playground) with the connection string above. It has sample datasets (read-only) you can experiment with.

```txt copy
https://explorer:@play.clickhouse.com:443/?database=default
```

    <Tabs.Tab>
      1. Log into your [ClickHouse Cloud console](https://clickhouse.cloud/)
      2. Go to your service details page
      3. Find "Connect" or "Connection Details" section
      4. Copy the HTTPS endpoint and your username/password
    </Tabs.Tab>
    <Tabs.Tab>
      - Check your ClickHouse config file (usually `/etc/clickhouse-server/config.xml`)
      - Look for `<http_port>` (default: 8123) and `<https_port>` (default: 8443)
      - Check users config in `/etc/clickhouse-server/users.xml` or users.d/ directory
      - Default user is often `default` with no password
    </Tabs.Tab>
    <Tabs.Tab>
      - Check your docker-compose.yml or docker run command for environment variables
      - Look for `CLICKHOUSE_USER`, `CLICKHOUSE_PASSWORD`, `CLICKHOUSE_DB`
      - Default is usually `http://default:@localhost:8123/?database=default`
    </Tabs.Tab>

- **Can't connect?** Try `curl http://your-host:8123/ping` to test connectivity
- **Authentication failed?** Verify username/password with `clickhouse-client --user=username --password=password`
- **Database not found?** Run `SHOW DATABASES` to see available databases
- **Permission denied?** Check user permissions with `SHOW GRANTS FOR username`

**Still stuck?** Check the [ClickHouse documentation](https://clickhouse.com/docs/en/getting-started/install) for your specific deployment method.

This will create a new Moose project from your ClickHouse database. [See Moose docs](https://docs.fiveonefour.com/moose) for more information about the project structure, and how it spins up your local development environment (including a local ClickHouse database).

The new project is called "my_project_name" and is created in the current directory. the string after `--from-remote` is the connection string to your ClickHouse database, structured as `clickhouse://<username>:<password>@<host>:<port>/<database>` (note, the ClickHouse Playground has no password).

### Install dependencies and run the dev server

Before you can run Moose's local dev server, Docker Desktop must be running.

Navigate into the project directory:

```bash filename="Terminal" copy
cd my_project_name
```

Install the dependencies: 

```bash filename="Terminal" copy
npm i
```

Run the dev server:

```bash filename="Terminal" copy
moose dev
```

### Get sample data

```bash filename="Terminal" copy
moose seed clickhouse --connection-string clickhouse://explorer:@play.clickhouse.com:9440/default --limit 100
```

This will seed your local ClickHouse database with 100 rows of sample data from your remote ClickHouse database—here, the ClickHouse Playground. You can change the number of rows with the `--limit` flag.

This will improve the context provided to Sloan's MCP tools, and make it easier to validate analytic engineering tasks.

### Set up your Client

The `sloan init` command above configured Cursor to use Sloan MCP tools. You can check this by opening Cursor and looking at `cursor > settings > cursor settings > MCP` menu. You should see `sloan` in the list of MCPs, alongside a list of tools. 

You may need to enable the MCP. Once you do so, you should see a green 🟢 status indicator next to it.

If you would like to use a different client, you can use the following command from within the project directory:

```bash filename="Terminal" copy
sloan setup --mcp <host>
```

### Enrich project with metadata [coming soon]

Since we have a Moose project with sample data and some metadata, we can use this to create more metadata! 

If we ask our client "Can you add a description to each Moose primitive in this project?", the LLM will use the `write_metadata` tool to add a description to each Moose primitive.

```TypeScript filename="my_project_name/index.ts"
const acPipeline = new IngestPipeline(
    "AircraftTrackingProcessed",
    {
      table: true,
      stream: true,
      ingestApi: false,
      metadata: {
          description: "Pipeline for ingesting raw aircraft data" } // new description field!
      }

);
```

### Chat with your data

You can also now just chat with your client about your data! Try asking "Look at my MTA data in ClickHouse, tell me about the trains that ran in the last 24 hours."

The client will use `read_moose_project`, `read_clickhouse_tables` and maybe `read_production_clickhouse` to answer your question.

### Create new Egress APIs with Sloan MCP tools

If you find a thread that you find interesting enough to want to productionize, try asking the client "can you create an egress API to furnish that data?"

The client will use `create_egress_api` and `test_egress_api` to create an egress API primitives in Moose, that will automatically deploy in your local dev environment when you save.

### What's next?

Try adding new [ingestion scripts, data models, or materialized views to your project using Sloan's experimental tools](https://docs.fiveonefour.com/sloan/reference/tool-reference#experimental-moose-tools)!

## Other Quickstart Guides

---

## from-template

Source: sloan/guides/from-template.mdx

## Quickstart: AI powered OLAP templates
*Bootstrap a complete OLAP pipeline with a Moose template; with Sloan's AI tools already set up for you.*

This will get you started with a Moose data engineering project ingesting Aircraft Transponder data that you can use to learn about Sloan's Analytics Engineering MCP toolset.

- **OS**: macOS or Linux (WSL supported for Windows)
- **Docker Desktop/Engine**: [24.0.0+](https://docs.docker.com/get-started/get-docker/)
- **Node**: [version 20+](https://nodejs.org/en/download) (LTS recommended)
- **Anthropic API Key**: [Get one here](https://docs.anthropic.com/en/docs/initial-setup)
- **Client**: [Cursor](https://www.cursor.com/) or [Claude Desktop](https://claude.ai/download) or [Windsurf](https://windsurf.ai/download). For this particular use-case, we recommend Claude Desktop.

### Install Sloan and Moose CLIs

```bash filename="Terminal" copy
bash -i <(curl -fsSL https://fiveonefour.com/install.sh) sloan,moose
```

We'll be using generative MCP tools here, so make sure you add your Anthropic API key in install. If you installed without adding it, you can add it later with `sloan config keys anthropic <your-api-key>`.  If you need to create one, see: https://docs.anthropic.com/en/docs/initial-setup.

### Create a new Moose project from the ADS-B template

```bash filename="Terminal" copy
sloan init <project-name> ads-b
```

This will create a new Moose project using the ADS-B template to gather ADS-B (aircraft transponder) data that you can use to explore Sloan's MCP offerings. By default, it will create the project configured for use with Cursor (by creating `~/.cursor/mcp.config`), but if you would like to use Claude Desktop, append `--mcp claude-desktop`.

If you want to create an empty project, and build your own Data Models and ingestion, try `sloan init <project-name> typescript-empty` or `sloan init <project-name> python-empty`

### Install dependencies and run the dev server

Navigate into the created project directory: 

```bash filename="Terminal" copy
cd <project-name>
```

Install the dependencies: 

```bash filename="Terminal" copy
npm i
```

Run the dev server:

```bash filename="Terminal" copy
moose dev
```

### Set up your client: open Cursor and Enable the MCPs

Then open your code editor (e.g. by `cursor .`).

Cursor should prompt you to enable the MCP. If it doesn't, go to `cursor > settings > cursor settings > MCP` and enable the MCP called "sloan". Note, the tools will not all work until the dev server is run locally! Note, you might need to refresh the MCP until its status indicator shows 🟢.

### Start Ingesting Data

Run the command to start ingesting data with the configured ingest scripts: `moose workflow run military_aircraft_tracking`

You should start to see hundreds of live datapoints ingesting instantly!

### Enrich project with metadata [coming soon]

Since we have a Moose project with sample data and some metadata, we can use this to create more metadata! 

If we ask our client "Can you add a description to each Moose primitive in this project?", the LLM will use the `write_metadata` tool to add a description to each Moose primitive.

```TypeScript filename="my_project_name/index.ts"
const acPipeline = new IngestPipeline(
    "AircraftTrackingProcessed",
    {
      table: true,
      stream: true,
      ingestApi: false,
      metadata: {
          description: "Pipeline for ingesting raw aircraft data" } // new description field!
      }

);
```

### Chat with your data

You can also now just chat with your client about your data! Try asking "What aircraft are listed in the data I have available."

The client will use `read_moose_project`, `read_clickhouse_tables` and maybe `read_production_clickhouse` to answer your question.

### Create new Egress APIs with Sloan MCP tools

If you find a thread that you find interesting enough to want to productionize, try asking the client "can you create an egress API to furnish that data?"

The client will use `create_egress_api` and `test_egress_api` to create an egress API primitives in Moose, that will automatically deploy in your local dev environment when you save.

## Other Quickstart Guides