npm package: @schaake-solutions/mcp-server
Description: MCP server for Schaake Solutions OS - enables Claude Code integration
Author: Schaake Solutions
Latest version: 0.1.6

# @schaake-solutions/mcp-server

MCP (Model Context Protocol) server for Schaake Solutions OS. This package enables Claude Code users to query project data, view invoices, and submit feedback directly from their terminal.

## Installation

```bash
npm install @schaake-solutions/mcp-server
```

Or with pnpm:

```bash
pnpm add @schaake-solutions/mcp-server
```

## Setup

### 1. Get Your MCP Token

Contact your Schaake Solutions administrator to get an MCP token. Tokens come in two types:

- **Admin tokens**: Full access to all data and operations
- **Client tokens**: Scoped access to your projects only

### 2. Configure Claude Code

Add the MCP server to your Claude Code configuration file (`~/.claude/claude_desktop_config.json` or similar):

```json
{
  "mcpServers": {
    "schaake-os": {
      "command": "schaake-mcp",
      "env": {
        "SCHAAKE_MCP_TOKEN": "your-token-here"
      }
    }
  }
}
```

If you installed the package locally (not globally), you may need to use the full path:

```json
{
  "mcpServers": {
    "schaake-os": {
      "command": "npx",
      "args": ["@schaake-solutions/mcp-server"],
      "env": {
        "SCHAAKE_MCP_TOKEN": "your-token-here"
      }
    }
  }
}
```

### 3. Restart Claude Code

After updating your configuration, restart Claude Code to pick up the new MCP server.

## Available Tools

### Admin Tools

These tools are available to users with admin tokens:

| Tool | Description |
|------|-------------|
| `get_activities` | List work activities with filters (project, client, date range, tags) |
| `get_projects` | List all projects with client information |
| `get_clients` | List all clients with project counts |
| `get_invoices` | List invoices with filters (client, status, date range) |
| `get_dashboard_metrics` | Get aggregated metrics (revenue, unbilled hours, etc.) |
| `get_unbilled_hours` | Get unbilled work grouped by project |
| `get_action_items` | Get business alerts (overdue invoices, new feedback) |

### Client Tools

These tools are available to users with client tokens:

| Tool | Description |
|------|-------------|
| `get_my_activities` | List activities for your projects |
| `get_my_projects` | List your projects with status |
| `get_my_invoices` | List your invoices |
| `get_my_feedback` | List feedback you've submitted |
| `submit_feedback` | Submit new feedback (bugs, features, questions) |

## Usage Examples

Once configured, you can ask Claude things like:

**Admin queries:**
- "What activities were logged this week?"
- "Show me all overdue invoices"
- "How many unbilled hours are there for AI2 Incubator?"
- "What's the current dashboard status?"

**Client queries:**
- "What has Mark been working on for my projects?"
- "Show me my recent invoices"
- "Submit a bug report about the login page"

## Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `SCHAAKE_MCP_TOKEN` | Your MCP authentication token | Yes |
| `SCHAAKE_API_BASE_URL` | API base URL (defaults to production) | No |

## Troubleshooting

### "SCHAAKE_MCP_TOKEN not set"

Make sure you've added the token to your Claude Code configuration and restarted Claude Code.

### "Unauthorized" errors

- Check that your token is correct and hasn't been revoked
- Client tokens can only access `get_my_*` and `submit_feedback` tools

### "Failed to connect to API"

- Check your internet connection
- The Schaake Solutions OS server may be temporarily unavailable

### Tool not working

- Ensure you're using the correct tool for your token type
- Admin tools require an admin token
- Check the tool's required parameters

## Support

For issues with this MCP server, contact Schaake Solutions support or create an issue in the repository.

## License

MIT