Bridging the Tax Gap: Building an Open-Source MCP for South African Tax

IntroductionThe global landscape of Artificial Intelligence is moving at breakneck speed, with Generative AI driving "automated innovation" across nearly every sector. However, in South Africa, the adoption of these breakthrough tools remains cautious—particularly within the highly regulated financial and legal sectors.For small businesses (SMMEs) in South Africa, taxation compliance remains a significant bottleneck. The combination of dense legislation and the high cost of professional consultations often leaves entrepreneurs flying blind. To address this, we are initiating an open-source project leveraging the Model Context Protocol (MCP) specifically tailored for South African taxation.What is the Model Context Protocol (MCP)?To understand MCP, we first need to look at how standard AI interfaces work. When using a tool like ChatGPT, the model is often "sandboxed"—it cannot see your local files, access your private database, or trigger local scripts unless you manually upload data.Introduced by Anthropic in late 2024, MCP is an open-source standard that acts as a secure "connector." It allows AI models to interface with external data sources and tools in a standardized way. Instead of the AI simply telling you it can’t access your records, an MCP-enabled agent can "reach out" to your database or documents to perform real-time analysis.The Vision: A Taxation-Specific MCPImagine a business owner or tax practitioner who needs to determine the tax implications of a complex transaction. Instead of leafing through the Income Tax Act, they interact with a specialized AI agent.By using the Taxation MCP, users can:Reference Private Data: Securely link PDF invoices or transaction databases.Automate Calculations: Generate tax-accurate computations based on current SARS rules.Reduce Costs: Lower the barrier to entry for compliance, allowing SMMEs to focus on growth rather than paperwork.Technical Foundation: Building the General MCPOur tool utilizes the Vercel AI SDK to manage interactions with Large Language Models. The architecture begins with a server-side implementation, currently accessible via a Command-Line Interface (CLI).Below is the foundational index.ts file using the Google Gemini provider:import { ModelMessage, streamText } from 'ai';import { google } from "@ai-sdk/google";import 'dotenv/config';import * as readline from 'node:readline/promises';const terminal = readline.createInterface({ input: process.stdin, output: process.stdout,});const messages: ModelMessage[] = [];async function main() { // Ensure the API Key is correctly mapped from the environment if (!process.env.GOOGLE_GENERATIVE_AI_API_KEY) { const candidate = process.env.GOOGLE_GENERATIVE_AI_API_KEY || process.env.AI_API_KEY || process.env.OPENAI_API_KEY; if (candidate) { process.env.GOOGLE_GENERATIVE_AI_API_KEY = candidate; } else { console.error('Missing API Key. Please set GOOGLE_GENERATIVE_AI_API_KEY in your .env file.'); return; } } while (true) { const userInput = await terminal.question('You: '); messages.push({ role: 'user', content: userInput }); const result = streamText({ model: google("gemini-2.0-flash"), // Optimized for speed and reasoning messages, }); let fullResponse = ''; process.stdout.write('\nAssistant: '); for await (const delta of result.textStream) { fullResponse += delta; process.stdout.write(delta); } process.stdout.write('\n\n'); messages.push({ role: 'assistant', content: fullResponse }); }}main().catch(console.error);Defining the Intelligence: The System Promptconst systemPrompt "You are a professional South African Tax Consultant specializing in SARS (South African Revenue Service) regulations. Your goal is to provide accurate, clear, and helpful tax advice based on the Income Tax Act, VAT Act, and the latest 2026 Budget Speech updates.Key Context for 2026/27 Tax Year:PIT:Brackets adjusted for inflation. Tax-free threshold for individuals <65 is R99,000.VAT:Standard rate is 15%. Compulsory registration threshold increases to R2.3 million (effective 1 April 2026).Medical Credits:R376 (first two members), R254 (additional dependents).Savings: TFSA annual limit is R46,000; Retirement fund deduction limit is R430,000.CGT:Primary residence exclusion is R3 million; Annual exclusion for individuals is R50,000.Corporate Tax:Standard rate remains 27%.Style Guidelines:1. Use local terminology: "eFiling", "Provisional Tax", "IT12", "PAYE", "Section 18A".2. Mandatory Disclaimer:"I am an AI assistant, not a registered tax practitioner. Please verify specific details with a qualified professional or via the SARS website."3. For complex queries, recommend specific SARS Interpretation Notes or Practice Manuals.The Taxation MCP in Action: A Practical Example to illustrate the value of this open-source project, let's look at how the model handles a common query regarding personal income tax for the 2026/2027 tax year. Instead of a generic AI response, the MCP-integrated assistant uses the specific logic defined in our system prompt and (eventually) its connection to SARS data tables. Sample User Query:"How much income tax do I need to pay this year?"MCP Assistant Response:"That is a vital question for financial planning! To calculate your exact liability, I would need specific details about your gross income and deductions. However, based on the 2026/2027 South African tax framework, here is how your tax is determined:1. The Calculation Process. Gross Income: This includes your salary, bonuses, rental income, and investment returns.Taxable Income: We arrive at this by subtracting allowable deductions from your gross income.Tax Brackets: SARS uses a progressive system. For 2026/27, the tax-free threshold for individuals under 65 is R99,000.2. Key Deductions & Credits for 2026/27CategoryDetail / LimitRetirement FundsUp to 27.5% of income, capped at R430,000.Medical Credits: R376 for the first two members; R254 per additional dependent.TFSA Limit: Annual contributions up to R46,000.Section 18ADonations to registered PBOs (capped at 10% of taxable income).3. Rebates: All individuals qualify for the Primary Rebate. If you are over 65 or 75, additional secondary and tertiary rebates will further reduce your tax payable.Next StepsThis project is currently in its alpha stage. Our next milestone is to move beyond the CLI and implement the formal MCP server structure, allowing this "Tax Brain" to be plugged directly into IDEs or professional tax software and you can keep track of its progress through the following github repository https://github.com/suprisedr/sars_taxation_mcp 

import { ModelMessage, streamText } from 'ai';import { google } from "@ai-sdk/google";import 'dotenv/config';import * as readline from 'node:readline/promises';const terminal = readline.createInterface({  input: process.stdin,  output: process.stdout,});const messages: ModelMessage[] = [];async function main() {  // Ensure the API Key is correctly mapped from the environment  if (!process.env.GOOGLE_GENERATIVE_AI_API_KEY) {    const candidate = process.env.GOOGLE_GENERATIVE_AI_API_KEY || process.env.AI_API_KEY || process.env.OPENAI_API_KEY;    if (candidate) {      process.env.GOOGLE_GENERATIVE_AI_API_KEY = candidate;    } else {      console.error('Missing API Key. Please set GOOGLE_GENERATIVE_AI_API_KEY in your .env file.');      return;    }  }
  while (true) {    const userInput = await terminal.question('You: ');    messages.push({ role: 'user', content: userInput });
    const result = streamText({      model: google("gemini-2.0-flash"), // Optimized for speed and reasoning      messages,    });
    let fullResponse = '';    process.stdout.write('\nAssistant: ');
    for await (const delta of result.textStream) {      fullResponse += delta;      process.stdout.write(delta);    }
    process.stdout.write('\n\n');    messages.push({ role: 'assistant', content: fullResponse });  }}main().catch(console.error);