README
¶
kite-mcp-watchlist
Per-user watchlist CRUD with SQLite backend for the algo2go
ecosystem. Pure leaf — zero internal kc/* deps, zero algo2go
transitive deps. Stdlib + google/uuid + modernc.org/sqlite
(pure-Go, no CGO) only.
Used by Sundeepg98/kite-mcp-server
for the watchlist MCP toolset (add/remove/list watchlist symbols
per user, with cross-device sync via the SQLite store).
Why a separate module?
Per-user watchlist CRUD is a foundational primitive any algo2go
project (broker dashboards, monitoring, future trading bots) may
need independent of kite-mcp-server. Hosting as a module:
- Centralizes the watchlist storage contract across consumers
- Lets the SQLite schema + migrations version independently
- Pure leaf — zero deps on other algo2go modules; install cost is just the module + sqlite driver
Stability promise
v0.x — unstable. Type signatures may evolve. Pin v0.1.0
deliberately.
Install
go get github.com/algo2go/kite-mcp-watchlist@v0.1.0
Public API
Store— per-user watchlist CRUD (Add,Remove,List,Clear,Count)DB— schema + migrations + queriesNewStore(db *DB) *Store— constructorItem— watchlist entry with uuid primary key
Dependencies
github.com/google/uuid— primary keysgithub.com/stretchr/testify— assertionsmodernc.org/sqlite— pure-Go SQLite driver
No internal kc/* or algo2go transitive deps.
Reference consumer
Sundeepg98/kite-mcp-server
— consumed by:
kc/store_registry.go,kc/manager_struct.go,kc/manager_init.go— service wiringkc/usecases/watchlist_usecases.go— watchlist use caseskc/telegram/bot.go,kc/telegram/commands_test.go— Telegram integrationmcp/watchlist_tools.go— MCP tools (add_to_watchlist, list_watchlist, etc.)
License
MIT — see LICENSE.
Authors
Original design: Sundeepg98 (Zerodha Tech). Multi-module promotion (2026-05-10): algo2go contributors.
Documentation
¶
Index ¶
- Constants
- func InitTables(db WatchlistDB) error
- type Store
- func (s *Store) AddItem(email, watchlistID string, item *WatchlistItem) error
- func (s *Store) CreateWatchlist(email, name string) (string, error)
- func (s *Store) DeleteByEmail(email string)
- func (s *Store) DeleteWatchlist(email, watchlistID string) error
- func (s *Store) FindItemBySymbol(watchlistID, exchange, tradingsymbol string) *WatchlistItem
- func (s *Store) FindWatchlistByName(email, name string) *Watchlist
- func (s *Store) GetAllItems(email string) []*WatchlistItem
- func (s *Store) GetItems(watchlistID string) []*WatchlistItem
- func (s *Store) ItemCount(watchlistID string) int
- func (s *Store) ListWatchlists(email string) []*Watchlist
- func (s *Store) LoadFromDB() error
- func (s *Store) RemoveItem(email, watchlistID, itemID string) error
- func (s *Store) SetDB(db WatchlistDB)
- func (s *Store) SetLogger(logger *slog.Logger)
- type Watchlist
- type WatchlistDB
- type WatchlistItem
Constants ¶
const ( // MaxWatchlistsPerUser is the maximum number of watchlists a single user can have. MaxWatchlistsPerUser = 10 // MaxItemsPerWatchlist is the maximum number of items in a single watchlist. MaxItemsPerWatchlist = 50 )
Variables ¶
This section is empty.
Functions ¶
func InitTables ¶
func InitTables(db WatchlistDB) error
InitTables creates the watchlist tables if they don't exist.
Types ¶
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is a thread-safe in-memory store for watchlists and their items. Optionally backed by SQLite for persistence via SetDB.
func (*Store) AddItem ¶
func (s *Store) AddItem(email, watchlistID string, item *WatchlistItem) error
AddItem adds an instrument to a watchlist. Returns error if the watchlist has MaxItemsPerWatchlist items.
func (*Store) CreateWatchlist ¶
CreateWatchlist creates a new named watchlist for the user. Returns the watchlist ID. Returns error if user already has MaxWatchlistsPerUser.
func (*Store) DeleteByEmail ¶
DeleteByEmail removes all watchlists and their items for the given email. Used during account deletion to clean up all user data.
func (*Store) DeleteWatchlist ¶
DeleteWatchlist removes a watchlist and all its items.
func (*Store) FindItemBySymbol ¶
func (s *Store) FindItemBySymbol(watchlistID, exchange, tradingsymbol string) *WatchlistItem
FindItemBySymbol finds an item by exchange:tradingsymbol in a watchlist. Returns nil if not found.
func (*Store) FindWatchlistByName ¶
FindWatchlistByName returns the watchlist with the given name for the user. Returns nil if not found.
func (*Store) GetAllItems ¶
func (s *Store) GetAllItems(email string) []*WatchlistItem
GetAllItems returns all items across all watchlists for a user (for batch LTP).
func (*Store) GetItems ¶
func (s *Store) GetItems(watchlistID string) []*WatchlistItem
GetItems returns copies of all items in a watchlist.
func (*Store) ListWatchlists ¶
ListWatchlists returns all watchlists for the given email. Returns deep copies to prevent callers from mutating shared state.
func (*Store) LoadFromDB ¶
LoadFromDB populates the in-memory store from the database.
func (*Store) RemoveItem ¶
RemoveItem removes an instrument from a watchlist by item ID.
func (*Store) SetDB ¶
func (s *Store) SetDB(db WatchlistDB)
SetDB enables write-through persistence to the given SQLite database.
type Watchlist ¶
type Watchlist struct {
ID string `json:"id"`
Email string `json:"email"`
Name string `json:"name"`
SortOrder int `json:"sort_order"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
Watchlist represents a named group of instruments.
type WatchlistDB ¶
type WatchlistDB interface {
ExecDDL(ddl string) error
ExecInsert(query string, args ...any) error
RawQuery(query string, args ...any) (*sql.Rows, error)
QueryRow(query string, args ...any) *sql.Row
}
WatchlistDB is an optional persistence backend for watchlists. Implemented by alerts.DB to avoid circular imports (same pattern as SessionDB).
type WatchlistItem ¶
type WatchlistItem struct {
ID string `json:"id"`
WatchlistID string `json:"watchlist_id"`
Email string `json:"email"`
Exchange string `json:"exchange"`
Tradingsymbol string `json:"tradingsymbol"`
InstrumentToken uint32 `json:"instrument_token"`
Notes string `json:"notes,omitempty"`
TargetEntry float64 `json:"target_entry,omitempty"` // 0 = not set
TargetExit float64 `json:"target_exit,omitempty"` // 0 = not set
SortOrder int `json:"sort_order"`
AddedAt time.Time `json:"added_at"`
}
WatchlistItem represents a single instrument in a watchlist.
Source Files