npm package: @metarunelabs/standup-mcp
Description: MCP server to access standup logs from PostgreSQL database
Author: Metarune Labs
Latest version: 1.0.0

# Standup MCP Server

An MCP (Model Context Protocol) server that provides access to standup logs stored in a PostgreSQL database. This allows Claude to query your standup meeting logs, search for specific content, and retrieve historical standup data.

## Features

- 📋 **Get Recent Standups**: Retrieve the most recent standup meeting logs
- 📅 **Get Standup by Date**: Fetch standup logs for a specific date
- 🔍 **Search Standups**: Search through standup logs for keywords or topics

## Prerequisites

- Node.js (v18 or higher)
- PostgreSQL database
- Database credentials with read access to the `standup_archives` table

## Database Schema

The server expects a PostgreSQL table with the following structure:

```sql
CREATE TABLE IF NOT EXISTS standup_archives (
  id SERIAL PRIMARY KEY,
  session_date DATE NOT NULL UNIQUE,
  html_content TEXT,
  attendees TEXT[],
  raw_logs JSONB,
  created_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX IF NOT EXISTS idx_archive_date ON standup_archives(session_date);
```

## Quick Start with npx (Recommended)

The easiest way to use this MCP server is with `npx`. No installation required!

### Claude Desktop Configuration

Add this to your Claude Desktop config file:

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

```json
{
  "mcpServers": {
    "standup": {
      "command": "npx",
      "args": ["-y", "@metarunelabs/standup-mcp"],
      "env": {
        "DB_HOST": "your-db-host.com",
        "DB_PORT": "5432",
        "DB_NAME": "your_database_name",
        "DB_USER": "your_database_user",
        "DB_PASSWORD": "your_database_password"
      }
    }
  }
}
```

Replace the `env` values with your PostgreSQL database credentials, then restart Claude Desktop.

## Installation (Alternative)

If you prefer to run from source or develop locally:

### Step 1: Install Dependencies

```bash
yarn install
```

### Step 2: Configure Environment Variables

Edit the `.env` file with your database details:

```env
# PostgreSQL Database Configuration
DB_HOST=localhost
DB_PORT=5432
DB_NAME=your_database_name
DB_USER=your_database_user
DB_PASSWORD=your_database_password
```

**Note**: Update these values to match your PostgreSQL server configuration.

### Step 3: Test the Server

Test if the server can connect to PostgreSQL:

```bash
yarn start
```

You should see: `Standup MCP Server running on stdio`

### Step 4: Add to Claude Desktop (Local Development)

Add this to your Claude Desktop config:

```json
{
  "mcpServers": {
    "standup": {
      "command": "node",
      "args": ["/absolute/path/to/metarune-standup-mcp/index.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_NAME": "your_database_name",
        "DB_USER": "your_database_user",
        "DB_PASSWORD": "your_database_password"
      }
    }
  }
}
```

**Important**: Replace `/absolute/path/to/metarune-standup-mcp/index.js` with the actual full path to your index.js file, and update the database credentials.

### Step 5: Restart Claude Desktop

Close and reopen Claude Desktop completely for the changes to take effect.

### Step 4: Verify Connection

In Claude Desktop, you should see an MCP icon (🔌) indicating the server is connected. You can now use the standup tools!

## Usage Examples

Once connected to Claude, you can ask:

### Get Recent Standups
```
"Show me the last 3 standup meetings"
"What were the recent standup updates?"
```

### Get Standup by Date
```
"Show me the standup from October 22, 2025"
"What did the team discuss in yesterday's standup?"
```

### Search Standups
```
"Search standups for mentions of 'authentication feature'"
"Find all standups that mentioned 'bug fixes'"
```

## Available Tools

### 1. `get_recent_standups`
Retrieves the most recent standup meeting logs.

**Parameters**:
- `count` (optional): Number of standups to retrieve (default: 5, max: 20)

### 2. `get_standup_by_date`
Gets standup logs for a specific date.

**Parameters**:
- `date` (required): Date in YYYY-MM-DD format

### 3. `search_standups`
Searches through standup logs for keywords.

**Parameters**:
- `keyword` (required): Keyword or phrase to search
- `limit` (optional): Maximum results to return (default: 5)

## Troubleshooting

### "Failed to fetch recent standups" Error

**Possible causes**:
1. Invalid database credentials
2. Database server not accessible
3. Network connectivity issues
4. Database server is not running
5. Table `standup_archives` doesn't exist

**Solutions**:
- Verify your database credentials in `.env` file
- Check if PostgreSQL is running: `pg_isready -h localhost -p 5432`
- Test connection: `psql -h localhost -U your_user -d your_database`
- Verify table exists: `\dt standup_archives` in psql
- Check server logs for detailed error messages

### "No standup found" Message

**Possible causes**:
1. No data in the database for the requested date
2. Wrong date format
3. Data hasn't been inserted yet

**Solutions**:
- Check if data exists: `SELECT COUNT(*) FROM standup_archives;`
- Verify date format is YYYY-MM-DD
- Check specific date: `SELECT * FROM standup_archives WHERE session_date = '2025-01-11';`

### Server Not Appearing in Claude Desktop

**Solutions**:
1. Check the config file path is correct
2. Verify JSON syntax is valid
3. Use absolute paths (not relative)
4. Restart Claude Desktop completely
5. Check Claude Desktop logs for errors
6. Verify all environment variables are set correctly

## Architecture

```
┌─────────────────┐
│  Claude Desktop │
└────────┬────────┘
         │ MCP Protocol
         │
┌────────▼────────┐
│   MCP Server    │
│   (This App)    │
└────────┬────────┘
         │ SQL Queries
         │
┌────────▼────────┐
│   PostgreSQL    │
│  (Database)     │
└─────────────────┘
```

## Data Structure

The MCP server returns standup data in this format:

```json
{
  "id": 1,
  "date": "2025-01-11",
  "dateFormatted": "1/11/2025",
  "htmlContent": "<html>...</html>",
  "attendees": ["user1", "user2"],
  "createdAt": "2025-01-11T10:00:00.000Z"
}
```

## Security Notes

- Keep your `.env` file secure and never commit it to version control
- Use a database user with minimal required permissions (read-only access to `standup_archives` table)
- The MCP server runs locally and doesn't send data to external services
- Data is only accessible through Claude Desktop on your machine
- Consider using SSL/TLS for database connections in production

## Support

If you encounter issues:
1. Check the troubleshooting section above
2. Verify PostgreSQL is running and accessible
3. Test database connection with psql
4. Test the MCP server independently with `yarn start`
5. Check Claude Desktop logs for connection errors

## Publishing to npm

To publish this package to npm so others can use it with `npx`:

### Prerequisites
- npm account ([create one here](https://www.npmjs.com/signup))
- Must be logged in: `npm login`

### Publishing Steps

1. **Update version** (if needed):
   ```bash
   npm version patch  # or minor, or major
   ```

2. **Build/test** (optional):
   ```bash
   yarn start  # Test locally
   ```

3. **Publish to npm**:
   ```bash
   npm publish --access public
   ```

   Note: Use `--access public` for scoped packages like `@metarunelabs/standup-mcp`

4. **Verify publication**:
   ```bash
   npx @metarunelabs/standup-mcp
   ```

### Using the Published Package

Once published, anyone can use it with:

```json
{
  "mcpServers": {
    "standup": {
      "command": "npx",
      "args": ["-y", "@metarunelabs/standup-mcp"],
      "env": {
        "DB_HOST": "your-db-host.com",
        "DB_PORT": "5432",
        "DB_NAME": "your_db_name",
        "DB_USER": "your_db_user",
        "DB_PASSWORD": "your_db_password"
      }
    }
  }
}
```

## License

MIT