An AI-powered knowledge base and developer agent for the Infosys Finacle Core Banking scripting language. Enables developers to write correct Finacle Script using Claude Code as an AI pair programmer grounded in verified KB data.
Finacle Script is a proprietary 4GL language used to customize Infosys Finacle Core Banking. It has hundreds of built-in hooks, a large database schema, and strict language rules that are poorly documented for AI tools.
This project builds a structured KB that exposes all of that knowledge to Claude Code via an MCP server, so developers can:
- Describe what they need in plain English → get the right hook or table
- Generate Finacle scripts grounded in real KB data, not hallucinated APIs
- Understand the blast radius of any change before making it
- Work consistently across a team with shared coding standards
finacle_script_agent/
│
├── dev_guildeline/ # Language reference docs (19 files)
│ ├── control_statements.md
│ ├── sql_select_stmt.md
│ ├── cursor_select.md
│ ├── error_handling.md
│ └── ...
│
├── user-hook/ # User hook documentation (250 files)
│ ├── urhk-b2k-valdate.md
│ ├── urhk-dbcursoropenwithbind.md
│ ├── urhk-setorbout.md
│ └── yet-to-gain-knowledge.md ← gap tracker
│
├── data-dictionary/ # Finacle DB table docs (1,079 files)
│ ├── general-acct-mast-table.md (GAM)
│ ├── hist-tran-dtl-table.md (HTD)
│ └── yet-to-gain-knowledge.md ← gap tracker
│
├── loaders/ # Data pipeline scripts
│ ├── build_dependency_graph.py ← Neo4j graph loader
│ ├── sqlite_loader.py ← SQLite KB loader
│ └── qdrant_loader.py ← Vector embeddings loader
│
├── mcp_server/ # MCP server (Claude Code connects here)
│ ├── server.py ← 9 MCP tools over HTTP/SSE
│ ├── kb/ ← SQLite DB (generated, not in repo)
│ └── personas/
│ ├── developer.md ← Developer persona standards
│ └── developer_claude.md ← CLAUDE.md template for dev projects
│
├── icici/ # Sample spec + BR files
├── SPEC.md # Full system architecture spec
├── finacle-kb-todo.md # Work tracker
└── claude-conversation.md # Session history reference
| Store | Purpose | Port |
|---|---|---|
SQLite (mcp_server/kb/finacle_kb.db) | Exact lookups — hooks by function name, tables by synonym | Local file |
| Neo4j | Script dependency graph — impact analysis, call chains | 7687 |
| Qdrant | Semantic vector search — plain English → hook/table | 6333 |
| Ollama | Local embedding model (nomic-embed-text, 768d) | 11434 |
| Area | Status | Count |
|---|---|---|
| Language reference docs | Complete | 19 files |
| User hook docs (stable) | 35 done, 215 stubs | 250 total |
| Data dictionary tables | 1,079 parsed from PDF | 425 still missing |
| Script dependency graph | Complete | 3,741 scripts, 537 tables, 295 hooks |
| Component | Status |
|---|---|
Neo4j dependency graph loader (build_dependency_graph.py) | Complete + watch mode |
SQLite KB loader (sqlite_loader.py) | Complete |
Qdrant vector loader (qdrant_loader.py) | Complete |
MCP server — 9 tools over SSE (server.py) | Complete |
| Developer persona + CLAUDE.md template | Complete |
| Tool | Description |
|---|---|
get_hook(function_name) | Full hook doc — signature, params, patterns |
get_table(table_name) | Table columns and usage by name or synonym |
get_guideline(topic) | Language construct documentation |
search_kb(query, category?) | Semantic search — plain English to KB entry |
impact_analysis(name, node_type) | Blast radius if table/hook/script changes |
find_callers(script_name) | Who calls this script |
find_call_chain(script_name) | Full call tree from a script |
get_persona(name) | Load developer standards and rules |
get_claude_md(name) | CLAUDE.md template for new developer projects |
# Python packages
pip install mcp neo4j pyyaml qdrant-client ollama watchdog
# Services# Neo4j — install from https://neo4j.com/download/ (bolt://localhost:7687, neo4j/password)# Qdrant — install from https://qdrant.tech/documentation/quick-start/ (http://localhost:6333)# Ollama — install from https://ollama.com/download (http://localhost:11434)
ollama pull nomic-embed-textRun these once after cloning, then keep the MCP server running for developers.
# 1. Clone
git clone https://github.com/rvalavan/finacle_script_agent
cd finacle_script_agent
# 2. Build SQLite KB (not stored in repo)
python loaders/sqlite_loader.py
# 3. Load Neo4j dependency graph# Point --scr-dir at your Finacle script corpus
python loaders/build_dependency_graph.py --scr-dir "C:/path/to/finacle/scr"# 4. Load Qdrant embeddings
python loaders/qdrant_loader.py
# 5. Start MCP server# Use --host 0.0.0.0 when running on a VM for team access
python mcp_server/server.py --host 127.0.0.1 --port 8765python loaders/build_dependency_graph.py --watchEach developer creates a project folder and connects to the running MCP server.
# 1. Create project folder (outside this repo)
mkdir c:\projects\my-feature
cd c:\projects\my-feature
git init
# 2. Create .mcp.jsonecho'{"mcpServers":{"finacle-kb":{"type":"sse","url":"http://<server-ip>:8765/sse"}}}'> .mcp.json
# 3. Open in VS Code
code .In Claude Code, type:
"Initialize this as a Finacle developer project"
Claude Code calls get_claude_md("developer"), writes CLAUDE.md and .claudeignore to the project. Start a new session — the developer persona loads automatically every time.
Then give Claude Code a spec file:
"Build a Finacle script based on specs/my-feature_spec.md"
See finacle-kb-todo.md for the full tracker. Priority areas for the AI engineering team:
Each stub in user-hook/ needs to be filled with real usage patterns sourced from the script corpus.
How to contribute:
- Pick a hook from
user-hook/yet-to-gain-knowledge.md - Search the script corpus for real usage:
grep -r "urhk_FunctionName" /path/to/scr/ - Extract patterns — how is it called? What are the inputs/outputs? What errors are common?
- Fill the stub MD file following the structure of a stable doc (e.g.
urhk-b2k-valdate.md) - Change
status: draft→status: stablein frontmatter - Run
python loaders/sqlite_loader.pyandpython loaders/qdrant_loader.pyto refresh
Priority hooks (most used, stubs exist):
urhk_TBAF_ShowUserException— companion to PutUserException (141 scripts)urhk_ExecSRVNoCommit— service call without commiturhk_facValidateUser— user authorization check
Missing topics in dev_guildeline/:
| Topic | File to create |
|---|---|
| MTTS transaction scripting pattern | mtts_pattern.md |
| SRV service layer scripting | srv_pattern.md |
| ORB response building (SetOrbOut/Err/Warning) | orb_response.md |
| Batch job lifecycle (BOD/EOD/BJS) | batch_lifecycle.md |
| File I/O (fileOpen → read/write → fileClose) | file_io.md |
| GOSUB subroutine pattern | gosub_pattern.md |
| Built-in date arithmetic (SYSDATE, TODAY) | date_arithmetic.md |
| STR$ / VAL — type conversion | str_val.md |
| CERR structured error propagation | cerr_pattern.md |
Follow the frontmatter schema in any existing guideline file.
Top priority tables by script usage:
| Table | Synonym | Scripts | Module |
|---|---|---|---|
TBAADM | TBA | 76 | Treasury |
ICI_GBM_CHALLAN_MASTER | — | 51 | Challan |
WLCKM | — | 51 | Workflow Lien |
CLMT | — | 50 | Clearing |
Source from the Finacle Data Dictionary PDF. Use loaders/parse_data_dictionary.py as a starting point.
Automate generating spec files for existing scripts using Claude API + KB context.
File to create:loaders/generate_script_specs.py
What it should do:
- Read a
.scrfile - Query the KB for each hook and table it uses
- Call Claude API with the script + KB context
- Output
specs/<module>/<script>_spec.md(business spec) and_br.md(business rules) - Skip scripts that already have a spec
Reference:icici/acm_CFR_Validation_spec.md is a hand-written example of the target output.
Beyond the developer persona, two more are planned:
| Persona | Files to create | Tools to add |
|---|---|---|
| Trainer | personas/trainer.md, trainer_claude.md | explain, show_example, quiz |
| BA & Tester | personas/ba.md, ba_claude.md | get_br, generate_br, generate_tests |
Add each persona's tools to mcp_server/server.py and its text blob to mcp_server/personas/.
File to create:loaders/kb_feedback_loop.py
When a developer writes or modifies a .scr file:
- Re-parse with
build_dependency_graph.py(watch mode already handles this) - Extract new patterns → candidate for
patterns/docs - Re-embed changed files in Qdrant
- Update Neo4j Script node + relationships
File to create:loaders/utils/validate_docs.py
Validates frontmatter in all MD files against JSON schemas in schemas/.
Ensures id, title, category, status, tags, version are always present and correctly typed.
Every KB document must have this YAML frontmatter:
---
id: unique-kebab-case-idtitle: Human Readable Titlecategory: user-hook | data-dictionary | languagefunction: urhk_FunctionName # hooks onlysynonym: TABLE_ALIAS # tables onlymodule: ACCT | GL | TM | ...tags: [tag1, tag2]version: "11.x"status: stable | draftrelated: [other-doc-id]
---Code blocks must use ```finacle language tag.
| File | Read this to understand |
|---|---|
SPEC.md | Full system architecture and design decisions |
CLAUDE.md | How Claude Code is configured to work in this repo |
finacle-kb-todo.md | What's done and what's next (area-by-area) |
claude-conversation.md | Full build session history with decisions and patterns |
user-hook/urhk-b2k-valdate.md | Example of a well-written stable hook doc |
dev_guildeline/cursor_select.md | Example of a well-written guideline doc |
icici/acm_CFR_Validation_spec.md | Example of a script spec (target for Area 4) |
| Variable | Default | Purpose |
|---|---|---|
NEO4J_URI | bolt://localhost:7687 | Neo4j connection |
NEO4J_USER | neo4j | Neo4j username |
NEO4J_PASSWORD | password | Neo4j password |
QDRANT_URL | http://localhost:6333 | Qdrant connection |
MCP_HOST | 127.0.0.1 | MCP server bind host |
MCP_PORT | 8765 | MCP server port |
Defaults are hardcoded in each loader/server file and can be overridden via CLI args.