vechemoga-mcp-server

vechemoga-mcp-server

An MCP server that lets an AI assistant read VecheMoga'slogs, query its database read-only, and inspect what the API actually sent to Loops andStripe — without leaving the editor.

One server, two deployments, identical tool names. The only difference is where the datacomes from:

That is MCP_LOG_BACKEND=docker|cloudwatch, one environment variable. It is deliberatelyone codebase: Sesame — the system this is ported from — has a local server.py and an AWSserver.py that have drifted into ~1400 and ~1800 lines of largely duplicated tool code.Do not fork this to add an environment. Add a backend.

Dev only. There is no prod MCP server, on purpose. A bearer token that can SELECTfrom the production database and read every production log stream is a materiallydifferent risk decision, and not one that should arrive as a side effect of this repo.

Tools

Fifteen, all read-only. Tools whose source is not configured in a given deployment are notregistered at all — an assistant that cannot see deploy_status locally will pick anotherroute, whereas one that calls it and gets an error will not.

PostgreSQL — pg_list_schemas, pg_list_tables, pg_describe_table, pg_query,pg_migration_status

pg_query takes a single SELECT / WITH … SELECT / EXPLAIN SELECT, adds a LIMIT whenthere is none, caps at 200 rows, and runs under SET TRANSACTION READ ONLY with a 10sstatement timeout. That is the second lock, not the first — see Read-onlybelow. pg_migration_status reads Liquibase's databasechangelog, which answers "did thisenvironment actually run the migration I merged?"

Logs — api_logs, api_liquibase_logs, web_logs, wiremock_logs, postgres_logs,pipeline_logs, automation_logs

All take the same four arguments: tail, since, until, grep. grep is applied afterretrieval, so narrowing with since/until beats a large tail. automation_logs earnsits place: a green Allure report can hide a failed Before/After hook, and the CodeBuildlog is the only place that failure is visible.

WireMock — wiremock_list_mappings, wiremock_find_requests

wiremock_find_requests answers did the API actually call Loops, and with what body? —which CloudWatch cannot, because WireMock's request logging is deliberately switched off sothat verification links never reach a log group. Strictly the read-only subset of the adminAPI: no mapping registration, and never /__admin/reset or a DELETE. ParallelCucumber workers and manual developers share that service and a global reset takes theirwork with it.

Delivery — deploy_status

codepipeline:GetPipelineState across the pipelines, including vechemoga-infra. Answers"is dev running the commit I think it is?" and "is an infra change sitting at the approvalgate?" It cannot start, approve or retry anything.

Read-only

Worth being precise about, because "the server only sends SELECTs" is not a securityproperty — it is a hope about a program.

1. The PostgreSQL role is the guarantee. vechemoga_mcp_reader holds GRANT SELECTand nothing else, with default_transaction_read_only = on. A bug in this repo cannotwrite to that database, because the credential it holds cannot.
2. The security group is the second. It permits a TCP connection from the dev-tools boxand the API box. What that connection may do is decided in (1).
3. The SQL guard in pg_query is the third, and its job is to turn a mistake into aclear error rather than a permission denial.

The build refuses to push if (3) regresses — buildspec-build.yml drives DELETE, UPDATE,DROP, INSERT and a stacked SELECT 1; DROP TABLE through it and fails if any is accepted.

Why no port 80

The dev-tools security group allows 443 from a handful of named operator addresses andnothing else. An HTTP-01 or TLS-ALPN-01 ACME challenge must be answerable from Let'sEncrypt's own validation addresses, which are not knowable in advance — either would force aport open to 0.0.0.0/0 and demote that allowlist from a security-group boundary to anapplication-layer matcher.

So Caddy proves the certificate over a Route 53 DNS-01 challenge, which needs no inboundreachability at all. That is what caddy/Dockerfile is for (xcaddy withcaddy-dns/route53), and the build fails if the plugin is missing rather than letting thebox fall back to a challenge that cannot work.

If certificate issuance fails, fix the Route 53 grant — do not open port 80.

What the server logs

Which tool ran and with which argument names. Never results. A pg_query answer or aWireMock journal entry would put database rows and verification links into/vechemoga/dev/mcp-server, where they would then live for 30 days — the exact hazardWireMock's own request logging is kept off to avoid.

Local development

The image is pulled from ECR by VecheMogaLocal's compose stack. To work on the serveritself:

pip install -r requirements.txt

MCP_LOG_BACKEND=docker \
MCP_DOCKER_CONTAINERS='{"api":"docker-api-1","web":"docker-web-1","postgres":"docker-postgres-1","wiremock":"docker-provider-proxy-1"}' \
POSTGRES_HOST=localhost POSTGRES_USER=vechemoga POSTGRES_PASSWORD=vechemoga POSTGRES_SSLMODE=disable \
WIREMOCK_ADMIN_URL=http://localhost:1080 \
python server.py

Then point your editor at http://localhost:8417/mcp. Container names come fromdocker compose ps --format '{{.Name}}' in VecheMogaLocal — they carry the compose projectprefix.

Do not test the endpoint with curl. It speaks MCP, not REST; a curl against /mcptells you nothing except that TLS and auth work. Validate by asking your assistant to calla tool, e.g. "list the schemas in the dev database".

Deployment

Two pipelines write to the dev-tools box, and this repo owns the compose file both of themdeploy into — exactly as VecheMogaApi/deploy owns the file the provider-mock pipelinedeploys into today:

Source (GitHub main, CodeConnections)
  └─▶ Build   CodeBuild ARM · buildspec-build.yml
        docker build ×2 (server + caddy, native arm64) → smoke checks
        → ECR :<sha12>  (only if the checks passed)
  └─▶ Deploy  CodeBuild · buildspec-deploy.yml → infra/deploy-to-instance.sh
        SSM Run Command on the dev-tools box: pull the pinned tags, up, health-check

Deploys are pinned to the git SHA. Rollback is Release change on an older execution, orIMAGE_TAG=<old-sha> ./infra/deploy-to-instance.sh from a laptop.

The Deploy stage skips green when the box is absent or stopped — it sleeps nightly23:30–07:45 Europe/Sofia. A pipeline that goes red every evening for a working reasonteaches everyone to stop reading it.

One-time, on the box

Both pipelines run docker compose against a checkout of this repo on the box — theydeploy images, they do not copy files. So the checkout has to exist before the first deploy,exactly as vechemoga-api is cloned onto the API box. Via SSM Session Manager (no SSH):

sudo git clone https://github.com/simo21-ss/vechemoga-mcp-server.git /opt/vechemoga-devtools
sudo chown -R ec2-user:ec2-user /opt/vechemoga-devtools

COMPOSE_DIR is therefore /opt/vechemoga-devtools/deploy — the clone root plus thisdirectory. It is set by Terraform on both deploy projects rather than left to thebuildspecs, because CodeBuild resolves an environment variable from the build projectdefinition ahead of the buildspec, and the target box and its compose path have to movetogether.

deploy/.env holds the non-secret wiring (the file is not committed; secrets are read fromSSM on the box at deploy time, by the instance role):

cat >> /opt/vechemoga-devtools/.env <<'EOF'
DB_HOST=veche-moga-db-dev.<...>.eu-central-1.rds.amazonaws.com
MCP_HOST=mcp.dev.vechemoga.bg
MCP_ALLOWED_IPS=176.12.9.148/32
MCP_LOG_GROUPS={"api":"/vechemoga/dev/api","wiremock":"/vechemoga/dev/provider-proxy","web":"/aws/amplify/<app-id>","pipeline":"/vechemoga/cicd/dev/deploy","automation":"/vechemoga/cicd/automation/test"}
MCP_PIPELINES=vechemoga-api-dev,vechemoga-web-dev,vechemoga-provider-proxy,vechemoga-automation,vechemoga-mcp-server,vechemoga-infra
PROVIDER_PROXY_IMAGE=<account>.dkr.ecr.eu-central-1.amazonaws.com/vechemoga/provider-proxy
EOF

And two SecureStrings, created by hand so their values never enter Terraform state —/vechemoga/dev/MCP_AUTH_TOKEN and /vechemoga/dev/MCP_DB_PASSWORD, plus thevechemoga_mcp_reader role. Runbook: VecheMogaInfra README → "Bring up the dev-toolsbox".

Infrastructure

The box, its security group, its IAM role, the ECR repositories and the pipeline areTerraform-managed in VecheMogaInfra (modules/dev-tools, modules/cicd-mcp,global/ecr.tf). This repo owns only what runs on the box. The design and its rollout arein VecheMogaInfra/docs/mcp-server-plan.md.