Saham Rakyat MCP Server

Production MCP server for Saham Rakyat data workflows.

Implemented now:

• news_latest
• news_search
• stock_price_latest
• stock_fundamental
• ohlcv_history
• broker_summary_history
• foreign_domestic_stock_flow
• sector_ohlc

Printing press CLI:

• pp_srmarket_macro
• srmarket-macro-pp-cli
• srmarket-macro-pp-mcp

Planned next:

• IHSG / OHLC tools
• stock fundamentals tools

Setup

npm install
cp .env.example .env

Fill .env with your Mongo and/or Redis connection.

Run

npm run dev

Printing press CLI:

npm run pp:srmarket-macro -- help

Installed binary names:

srmarket-macro-pp-cli help
srmarket-macro-pp-mcp

Remote HTTP mode:

MCP_TRANSPORT=http npm run dev

Build

npm run build
npm start

Package For Install

If you want to distribute this privately as an installable npm tarball:

npm run pack:local

That will produce a file like:

saham-rakyat-hermes-mcp-fundamental-0.1.0.tgz

Then install it on another machine or agent runtime with:

npm install -g ./saham-rakyat-hermes-mcp-fundamental-0.1.0.tgz

Available binaries after install:

srmarket-macro-pp-cli
srmarket-macro-pp-mcp
pp_srmarket_macro

If you later want to publish to a registry instead of using tarballs, change "private": true in package.json to false and set the package name/scope you want.

After build, the printing press entry is available at:

node dist/pp_srmarket_macro/index.js help

Docker

Build locally:

docker build -t saham-rakyat-hermes-mcp-fundamental:local .

Run with env file:

docker run --rm -i --env-file .env saham-rakyat-hermes-mcp-fundamental:local

In MCP_TRANSPORT=stdio mode, the container should be started by your MCP host or with docker run -i.

If you set MCP_TRANSPORT=http, the same container runs as a remote MCP HTTP server instead. In that mode, expose MCP_HTTP_PORT, for example:

docker run --rm -p 3000:3000 --env-file .env saham-rakyat-hermes-mcp-fundamental:local

GHCR Publish

The workflow at .github/workflows/publish-ghcr.yml publishes to:

ghcr.io/<owner>/<repo>

It runs on:

• manual dispatch from GitHub Actions

Example image reference:

ghcr.io/your-org/saham-rakyat-hermes-mcp-fundamental:latest

MCP Tools

news_latest

Returns the most recent news items sorted by source.date.

Inputs:

• limit: number of items, default 10, max 50
• daysBack: optional date window in days
• excerptLength: optional excerpt size, default 240

news_search

Searches by keyword across title and article content.

Ranking behavior:

• exact phrase matches in title are ranked highest
• exact phrase matches in content are boosted
• all-terms matches outrank partial matches
• newer articles break ties

Inputs:

• query: required search string
• limit: number of items, default 10, max 25
• daysBack: optional date window in days
• excerptLength: optional excerpt size, default 240

stock_price_latest

Looks up the latest Redis stock summary by key pattern KA.<STOCK_CODE>.<BOARD_CODE>.

The parser is strict:

• the Redis payload must split into exactly 47 fields on |
• if the payload shape changes, the tool returns an error instead of silently shifting fields

Inputs:

• stockCode: required stock code, normalized to uppercase, example BBCA
• boardCode: optional board code, normalized to uppercase, default RG

Returns pricing-focused fields:

• trade date and time
• previous, open, high, low, close
• change and percent change
• volume, value, frequency, average price
• best bid and offer prices and volumes
• theoretical price and volume

stock_fundamental

Calls the Samuel mini fundamental API with POST and groups the result into sections.

Inputs:

• stockCode: required stock code, normalized to uppercase, example BBCA
• year: required 4-digit year, example 2025
• qory: required mode, Y or Q

Returns:

• columns: the four returned comparison columns from the Quarter/Year row
• sections: grouped metrics such as Overview, Income Statement (M), Balance Sheet (M), Cash Flow (M), and Ratio
• each metric includes both the raw string value and parsed numeric value when possible

ohlcv_history

Calls the Samuel historical endpoint for either a stock or IHSG and normalizes the returned candles.

Inputs:

• market: stock or ihsg
• stockCode: required when market=stock, ignored for ihsg
• start: API window string such as 10y, default 10y
• groupBy: API grouping string such as daily, default daily
• limit: max number of candles returned by the MCP tool, default 120
• order: desc for newest-first or asc for oldest-first, default desc

Returns:

• response metadata: code, start, end, grouping, total candle count
• normalized candles with time, open, high, low, close, and volume

broker_summary_history

Calls the Samuel broker net buy/sell endpoint and returns parsed broker rows with computed net metrics.

Inputs:

• stockCode: required stock code, normalized to uppercase, example BBCA
• boardCode: one of ALL, RG, TN, NG, default RG
• type: one of FOREIGN, DOMESTIC, ALL, default ALL
• startDate: required date in YYYY-MM-DD
• endDate: required date in YYYY-MM-DD
• limit: max number of broker rows returned by the MCP tool, default 100

Returns:

• response metadata: stockCode, boardCode, type, from, to, total broker count
• rows: parsed broker rows with numeric buy/sell/net/total fields
• computedNetValue, computedNetLot, computedNetFrequency, computedNetVolume
• computedNetSide: buy, sell, or flat
• computedMatchesApi: whether the computed net values match the API-provided net values
• topNetBuyers and topNetSellers

Transport Modes

This server supports two MCP transports:

• stdio via MCP_TRANSPORT=stdio
• remote Streamable HTTP via MCP_TRANSPORT=http

HTTP mode env vars:

• MCP_HTTP_HOST: bind address, default 0.0.0.0
• MCP_HTTP_PORT: listening port, default 3000
• MCP_HTTP_PATH: MCP endpoint, default /mcp
• MCP_HTTP_HEALTH_PATH: health endpoint, default /health

Notes

The search implementation is domain-local and isolated from the MCP layer. That makes it safe to upgrade later to MongoDB text indexes, Atlas Search, or a dedicated search engine without changing the tool contract.

Printing Press CLI

pp_srmarket_macro is a terminal-first presentation layer built on top of the same service layer used by the MCP server. It does not replace MCP. It gives the current capabilities a clean CLI output format plus optional raw JSON.

It now follows Printing Press-style conventions:

• dual interface: srmarket-macro-pp-cli plus srmarket-macro-pp-mcp
• human-readable output in terminal
• auto-JSON when output is piped
• --compact for token-light agent output
• typed exit codes 0/2/3/4/5/7

Commands:

npm run pp:srmarket-macro -- news latest --limit 5
npm run pp:srmarket-macro -- news search --query "bbca rights issue"
npm run pp:srmarket-macro -- price latest --stock BBCA --board RG
npm run pp:srmarket-macro -- fundamental get --stock BBCA --year 2025 --qory Y
npm run pp:srmarket-macro -- ohlcv history --market stock --stock BBCA --limit 20
npm run pp:srmarket-macro -- ohlcv history --market ihsg --limit 20
npm run pp:srmarket-macro -- broker-summary history --stock BBCA --board RG --type ALL --start-date 2023-06-21 --end-date 2023-06-21 --limit 20
npm run pp:srmarket-macro -- foreign-domestic history --start-date 2026-06-02 --end-date 2026-06-02
npm run pp:srmarket-macro -- sector ohlc

Raw JSON mode:

npm run pp:srmarket-macro -- price latest --stock BBCA --json

Compact mode:

npm run pp:srmarket-macro -- broker-summary history --stock BBCA --board RG --type ALL --start-date 2023-06-21 --end-date 2023-06-21 --compact

Sources And Inspiration

• CLI Printing Press
• Printing Press Library

This repo keeps its existing TypeScript MCP implementation, but the pp_srmarket_macro layer now follows the Printing Press ecosystem conventions around naming, dual CLI/MCP interface, compact output, auto-JSON when piped, and typed exit codes.