> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airstore.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> Run MCP tools as CLI executables

<Note>
  Tools are primarily used in **local mode** where you configure MCP servers yourself. For the standard cloud experience with source views, see the [Quickstart](/quickstart).
</Note>

Tools are MCP servers exposed as executables in your Airstore filesystem. They let Claude (and you) take actions—create issues, send messages, query APIs.

## Where tools live

```bash theme={null}
ls ~/airstore/tools/
# filesystem  github  memory  wikipedia
```

Each tool is a virtual executable that wraps an MCP server.

## Running a tool

```bash theme={null}
~/airstore/tools/wikipedia search "something"
```

Output is JSON:

```json theme={null}
{
  "results": [
    {
      "title": "Something",
      "page_id": 8041208,
      "excerpt": "Something may refer to: Something (concept)..."
    }
  ]
}
```

## Available commands

Each tool has multiple commands. List them with `--help`:

```bash theme={null}
~/airstore/tools/filesystem --help
```

```
Available commands:
  list_directory    List contents of a directory
  read_file         Read a file
  write_file        Write to a file
  create_directory  Create a directory
  move_file         Move or rename a file
```

<Note>
  Command names and argument formats are defined by the underlying MCP server, not Airstore. Different servers may use different conventions (e.g., `list_directory` vs `list-directory`). Use `--help` to see the exact syntax for each tool.
</Note>

## Tool examples

### Filesystem

```bash theme={null}
# List a directory
~/airstore/tools/filesystem list_directory /tmp

# Read a file
~/airstore/tools/filesystem read_file /tmp/notes.txt
```

### Memory

The memory tool provides a knowledge graph:

```bash theme={null}
# Create entities
~/airstore/tools/memory create_entities '[{"name": "project", "type": "note", "observations": ["Started Q1 2024"]}]'

# Search entities
~/airstore/tools/memory search_entities "project"
```

### Wikipedia

```bash theme={null}
# Search Wikipedia
~/airstore/tools/wikipedia search "albert einstein"

# Get article content
~/airstore/tools/wikipedia get_article "Albert_Einstein"
```

### GitHub

```bash theme={null}
# List repositories
~/airstore/tools/github list_repositories --owner=acme

# List issues
~/airstore/tools/github list_issues --owner=acme --repo=api
```

<Note>
  The GitHub tool requires setting the `GITHUB_TOKEN` environment variable in your config file.
</Note>

## Piping tools

Tools output JSON, so you can pipe to `jq` or other Unix tools:

```bash theme={null}
# Parse with jq
~/airstore/tools/wikipedia search "einstein" | jq '.results[].title'

# Filter results
~/airstore/tools/filesystem list_directory /tmp | jq '.[] | select(.type == "file")'
```

Chain tools together:

```bash theme={null}
# Search and store in memory
RESULTS=$(~/airstore/tools/wikipedia search "Alan Turing" | jq -c '.results[0]')
~/airstore/tools/memory create_entities "[{\"name\": \"turing-research\", \"type\": \"note\", \"observations\": [$RESULTS]}]"
```

## Adding custom tools

Tools are configured in `config.local.yaml` under the `tools.mcp` section:

```yaml theme={null}
mode: local

gateway:
  grpc:
    port: 1993
  http:
    host: 127.0.0.1
    port: 1994

tools:
  mcp:
    # Each key becomes a tool name
    my-tool:
      command: npx
      args: ["-y", "@company/mcp-tool"]
      env:
        API_KEY: "${API_KEY}"
```

After mounting, the tool appears at `~/airstore/tools/my-tool`.

### Configuration options

| Field     | Description                                      |
| --------- | ------------------------------------------------ |
| `command` | Command to start the MCP server                  |
| `args`    | Arguments to pass to the command                 |
| `env`     | Environment variables (supports `${VAR}` syntax) |

### Example configurations

**Filesystem tool**:

```yaml theme={null}
tools:
  mcp:
    filesystem:
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp", "/Users"]
```

**GitHub tool** (requires token):

```yaml theme={null}
tools:
  mcp:
    github:
      command: npx
      args: ["-y", "@modelcontextprotocol/server-github"]
      env:
        GITHUB_TOKEN: "${GITHUB_TOKEN}"
```

**Custom internal tool**:

```yaml theme={null}
tools:
  mcp:
    internal-api:
      command: /usr/local/bin/internal-mcp
      env:
        API_URL: https://internal.company.com
        API_KEY: "${INTERNAL_API_KEY}"
```

## Building an MCP server

MCP servers implement the [Model Context Protocol](https://modelcontextprotocol.io/). Here's a minimal TypeScript example:

```typescript theme={null}
import { Server } from "@modelcontextprotocol/sdk/server";

const server = new Server({
  name: "my-tool",
  version: "1.0.0"
});

server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "hello",
      description: "Say hello",
      inputSchema: {
        type: "object",
        properties: {
          name: { type: "string", description: "Name to greet" }
        },
        required: ["name"]
      }
    }
  ]
}));

server.setRequestHandler("tools/call", async (request) => {
  const { name, arguments: args } = request.params;
  
  if (name === "hello") {
    return { 
      content: [{ type: "text", text: `Hello, ${args.name}!` }] 
    };
  }
});

server.connect(process.stdin, process.stdout);
```

## Error handling

Tools return non-zero exit codes on failure:

```bash theme={null}
~/airstore/tools/filesystem read_file /nonexistent/file
# Exit code: 1
# {"error": "File not found"}
```

Check exit codes in scripts:

```bash theme={null}
if ~/airstore/tools/filesystem list_directory /tmp; then
  echo "Listed successfully"
else
  echo "Failed to list directory"
fi
```

## Debugging

If a tool isn't working:

1. **Run the command directly** to check for errors:
   ```bash theme={null}
   npx -y @modelcontextprotocol/server-filesystem /tmp
   ```

2. **Check environment variables** are set:
   ```bash theme={null}
   echo $GITHUB_TOKEN
   ```

3. **Mount with verbose logging**:
   ```bash theme={null}
   airstore mount ~/airstore --config config.local.yaml --verbose
   ```

## Related

* [Source Views](/concepts/source-views) - Create views of the data you need
* [Using with Claude Code](/guides/claude-code) - Let Claude use your tools
* [Local deployment](/deployment/local) - Run tools locally