sharesight-mcp: Instructions file for Claude Code

CLAUDE.md - Project Instructions for Claude

This file provides guidance for Claude when working with the Sharesight MCP Server codebase.

Project Overview

This is an MCP (Model Context Protocol) server that wraps the Sharesight v3 API, allowing AI assistants to interact with Sharesight portfolio data through natural language.

Tech Stack:

• TypeScript
• Node.js 18+
• MCP SDK (@modelcontextprotocol/sdk)

Project Structure

sharesight-mcp/
├── src/
│   ├── index.ts              # CLI entry point with serve and auth commands
│   ├── oauth.ts              # OAuth 2.0 token management and refresh
│   ├── sharesight-client.ts  # HTTP client for Sharesight API
│   └── types.ts              # TypeScript interfaces for API types
├── dist/                     # Compiled output (gitignored)
├── package.json
├── tsconfig.json
└── README.md

Key Files

src/index.ts

The main CLI entry point with two commands:

• sharesight-mcp serve - Run the MCP server (default)
• sharesight-mcp auth - One-time OAuth authentication Contains tool definitions using Zod schemas for validation.

src/oauth.ts

OAuth 2.0 manager class handling:

• Authorization URL generation
• Token exchange and storage
• Automatic token refresh

src/sharesight-client.ts

HTTP client class with methods for each API endpoint. All methods:

• Are async and return typed responses
• Use the private request() method for HTTP calls
• Handle query parameters and request bodies

src/types.ts

TypeScript interfaces matching Sharesight API v3 response structures. Organized into:

• Common types (ApiTransaction, Currency, Pagination)
• Domain types (Portfolio, Holding, CustomInvestment, etc.)
• Response types (PortfoliosResponse, HoldingsResponse, etc.)
• Request types (CreateCustomInvestmentRequest, etc.)

Build Commands

npm install     # Install dependencies
npm run build   # Compile TypeScript to dist/
npm run dev     # Watch mode for development
npm start       # Run the compiled server